Search documentation v0.6.1

Select

Choose an option from a predefined list, displayed in a dropdown

Source ↗️ Report Issue ↗️

The Select component is an extended List component. Any prop that the List component can accept, can also be used by the Select component. To better understand how this component works, we recommend reading through the documentation of the List component first.

Preview
How to use Selects in Astro
---
import { Select } from 'webcoreui/astro'
---
<Select
name="select-id"
itemGroups={[...]}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
/>
<script>
import { listen } from 'webcoreui'
listen('selectOnChange', event => {
console.log(event)
})
</script>
How to use Selects in Svelte
<script>
import { Select } from 'webcoreui/svelte'
</script>
<Select
name="select-id"
itemGroups={[...]}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
onChange={event => console.log(event)}
/>
How to use Selects in React
import React from 'react'
import { Select } from 'webcoreui/react'
const Component = () => (
<Select
name="select-id"
itemGroups={[...]}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
onChange={event => console.log(event)}
/>
)
export default Component
You can see the exact value of the itemGroups prop used in the above example in this section.

To handle select events, listen to the selectOnChange event in Astro, or use the onChange prop for Svelte and React components. The event object returns the following properties:

Event object
{
select: 'select-id' // The name prop of the Select component
value: 'new', // Value of the clicked item
name: 'Create issue', // Name of the clicked item
list: ul._list_1rduk_1 // HTMLUListElement - the ul which the item belongs to
}

States

The select event is only triggered for active Select components. To disable a Select component, set the disabled prop to true:

Disabled Select
<Select
name="select-id"
itemGroups={[...]}
disabled={true}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
/>

If you’d like to use the Select component as a command list or as a combobox, you can disable automatic value update to keep its placeholder/value intact using the updateValue prop:

<Select
name="select-id"
itemGroups={[...]}
value="Take an action"
updateValue={false}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
/>

Labels

The Select component can be labelled in three different ways using the following props:

<Select
name="select-id"
label="Commonly used actions"
itemGroups={[...]}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
/>
<Select
name="select-id"
placeholder="Commonly used actions"
itemGroups={[...]}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
/>
<Select
name="select-id"
subText="Take an action or jump to a page"
itemGroups={[...]}
showSearchBar={true}
showSearchBarIcon={true}
searchBarPlaceholder="Filter options"
/>

Positioning

By default, options are displayed under the Select component. These options can be repositioned using the position prop. Please see the API documentation below for all possible position values. The following three Select components demonstrate the left, right, and modal positions.

Automatic repositioning during filtering with custom positions is currently not supported.

API

type SelectProps = {
name: string
value?: string
placeholder?: string
label?: string
subText?: string
disabled?: boolean
updateValue?: boolean
position?: 'top'
| 'bottom'
| 'left'
| 'left-start'
| 'left-end'
| 'right'
| 'right-start'
| 'right-end'
| 'modal'
} & ListProps
type SvelteSelectProps = {
onChange?: (event: ListEventType & { select: string }) => void
} & SelectProps
type ReactSelectProps = {
onChange?: (event: ListEventType & { select: string }) => void
} & SelectProps
For the ListProps and ListEventType types, please see the API documentation of the List component.
PropPurpose
name Sets a unique name for the select that.
value Sets a default value for the select.
placeholder Sets a placeholder for the select.
label Sets a label for the select that appears above the input.
label Sets a label for the select that appears below the input.
disabled Disables the select.
updateValue Sets whether the value of the select should be updated on interaction. Defaults to true.
position Sets the position of the options, relative to the select. Defaults to bottom.
Svelte & React PropPurpose
onChange Attach an on-change event listener that is triggered when an option is selected.

Request improvement for this page