Select
Use Select in a form when the value must be one, or several, of a known set of options: a country, a role, labels. When any text is valid and the options are only suggestions, use AutoComplete; for two to five short options that fit on screen, SegmentedControl; outside a form, Popselect opens the same list from any trigger.
Select is a field that opens a menu of options: pick one, or several (shown as tags) with multiple, and type to filter with filterable. It shares its option list with Popselect. Focus stays in the field the whole time: it is the combobox that drives the list, as in the WAI-ARIA combobox pattern.
#Demos
#Basic
Click the field, or focus it and press ↓ / Enter / Space, to open the menu. The menu is as wide as the field and opens below it, flipping above when there is no room. Disabled options are skipped.
#Multiple
multiple shows the chosen options as tags (× removes one) and keeps the menu open; the value is an array. maxTagCount shows the first few tags and a +N tag. clearable shows a clear button when hovering a field with a value.
#Filterable
filterable lets you type in the field to filter the options (by label, case-insensitive; pass filter to change that). The first match is active, so Enter picks it.
#Filterable and multiple
With both, typing filters the list and Enter adds the active option as a tag; the menu stays open and the typed text clears after each pick (clearFilterAfterSelect), ready for the next name. Backspace in an empty filter removes the last tag, and × on a tag removes that one.
#Remote search
With remote, Select doesn’t filter: onSearch gets the typed text and you pass the options for it. loading shows a spinner in place of the chevron.
#Size and status
size sets the field’s height (it lines up with buttons of the same size); status colors the border.
#Keyboard
With focus in the field: ↓ / ↑ / Enter (and Space unless filterable) open the menu; ↑ / ↓ move the active option (skipping disabled ones and wrapping); Enter picks it; Home / End and typing a letter jump, unless filterable (then they edit the text); Escape closes; Tab closes and moves on.
#Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
options | SelectMixedOption[] | required | Options { label, value, disabled? }, optionally in groups { type: "group", label, key, children }. | Unreleased |
value | SelectValue | SelectValue[] | null | undefined | Controlled value; an array with multiple. | Unreleased |
defaultValue | SelectValue | SelectValue[] | null | null | Initial value when uncontrolled. | Unreleased |
onUpdateValue | (value, option) => void | undefined | Called with the new value and the chosen option(s). | Unreleased |
multiple | boolean | false | Pick several, shown as tags. | Unreleased |
filterable | boolean | false | Type in the field to filter. | Unreleased |
filter | (pattern, option) => boolean | label contains | Whether an option matches the typed text. | Unreleased |
onSearch | (pattern: string) => void | undefined | Called as the user types. | Unreleased |
remote | boolean | false | Don’t filter here; the options come from onSearch. | Unreleased |
clearFilterAfterSelect | boolean | true | With multiple, clear the typed text after picking. | Unreleased |
clearable | boolean | false | Show a clear button on hover when there is a value. | Unreleased |
onClear | () => void | undefined | Called after clearing. | Unreleased |
placeholder | ReactNode | locale “Please select” | Shown with no value. | Unreleased |
size | small | medium | large | medium | Field height and text size. | Unreleased |
status | success | warning | error | undefined | Border color. | Unreleased |
disabled | boolean | false | Can’t be opened or changed. | Unreleased |
loading | boolean | false | A spinner replaces the chevron. | Unreleased |
maxTagCount | number | undefined | With multiple, show at most this many tags, then +N. | Unreleased |
renderLabel | (option, selected) => ReactNode | undefined | Custom label, in the menu and the field. | Unreleased |
renderTag | (option, remove) => ReactNode | undefined | Custom tag for a chosen option. | Unreleased |
consistentMenuWidth | boolean | true | The menu is exactly as wide as the field; otherwise at least as wide. | Unreleased |
placement | PopoverPlacement | bottom-start | Where the menu opens. | Unreleased |
show / defaultShow | boolean | undefined / false | Controlled / initial menu state. | Unreleased |
onUpdateShow | (show: boolean) => void | undefined | Called when the menu opens or closes. | Unreleased |
header / footer | ReactNode | undefined | Rows above / below the options. | Unreleased |
empty | ReactNode | locale “No data” | Shown when there are no options. | Unreleased |
to / zIndex | Same as Popover. | Unreleased | ||
onFocus / onBlur | (event) => void | undefined | Focus entering / leaving the field. | Unreleased |
aria-label, aria-labelledby and id go to the combobox element; className, style and ref to the field.