Combobox presents user with a set of options and allows to select one of them.
Combobox should be disabled, when user shouldn't be allowed to interact with it.
Individual options can be disabled too.
You can also provide a custom message when an option is disabled:
Mark combobox as loading, when options are fetched on the fly and are not yet available.
Invalid combobox indicates that current value isn't what the system expects.
Clearable combobox should be used when empty selection is acceptable.
Options can display an additional descriptive text underneath the label.
Options can display additional accessories view before and after the label. You can show an image using an image accessory. This is useful for showing logos when selecting sources or destinations, for example.
Additionally, using the showPlaceholderIcon prop will render a dotted circle in the placeholder state.
Icons can be accessories too.
Accessories can be shown on the left or right.
The combobox supports filtering options based on the input value. This state is accessible via the onSearchUpdate prop. Any change that's typed in the input will call this function.
Set renderInputInControl to false to render the combobox input inside of the popover.
You can disable sorting and filtering internally by setting disableSortingAndFiltering to true. This could be helpful if the options are already sorted and filtered externally.
Combobox allows user to create a new option on the fly, when no suitable option exists.
For that, enable supportsCreatableOptions and set an onCreateOption function that will handle creation of options.
Options can be created asynchronously, but you need to handle loading state yourself via isLoading prop.
You don't have to create objects with label and value keys as shown in the examples above.
Combobox supports any objects, as long as you provide a label and value for each option via optionLabel and optionValue functions.
description may be replaced with the optionDescription function.
There's a version of Combobox called GroupedCombobox, that supports groups of options.
Use the heavy variant to emphasize the combobox when in views with many selects or in-line with text.
Use the alternative variant to deemphasize the combobox when there are many selects.
The size prop impacts font-size and height. Default is set to md.
To set the width, use the width prop instead.
When rendering smaller-width comboboxes, you may end up with options that are quite tall. To make the options easier to read, pass in a specific width for the popover using popoverWidth.
It is recommended to match widths, when possible.
| Name | Default | Description |
|---|---|---|
isDisabled | — | booleanDetermines if combobox is disabled. |
isLoading | — | booleanIndicates that options are being loaded. |
isInvalid | — | booleanIndicates that combobox is in invalid state. |
isClearable | false | booleanDetermines if selection can be cleared. |
isOptionDisabled | — | (option: Option) => boolean | stringFunction to determine whether an option should be disabled. If a string is returned, it will be used as a disabled message. |
emptyOptionsMessage | "No options" | stringText to show inside a dropdown when there are no options. |
supportsCreatableOptions | — | booleanDetermines if user is allowed to create a new option, if it's not present already. |
createOptionMessage | "Create "[input value]"" | (inputValue: string) => stringText to show inside dropdown when creating a new option. |
disableSortingAndFiltering | false | booleanDetermines if the options should be sorted and filtered internally. |
comboboxRef | — | RefObject<HTMLInputElement>Reference to the combobox input element. |
options | — | Option[]Available options. `Option` is a generic, so type of options will be inferred. |
optionLabel | — | (option: Option) => stringFunction to extract label from an option. If it's not provided, `label` field will be used as a label. |
optionDescription | — | (option: Option) => stringFunction to extract description from an option. If it's not provided, `description` field will be used as a label. |
optionValue | — | (option: Option) => OptionValueFunction to extract value from an option. If it's not provided, `value` field will be used as a value. |
optionAccessories | — | SelectOptionAccessoriesGetter<Option>Function to show accessories near the option label. |
placeholder | — | stringText to show inside combobox when no option is selected. |
removePortal | false | booleanDetermines if the select dropdown should be rendered in a portal. |
renderInputInControl | true | booleanDetermines if the input should be rendered in the control. |
showPlaceholderIcon | false | booleanDetermines if the placeholder icon should be shown. Only available when optionAccessory is defined. |
value | — | OptionValue | undefinedSelected option. |
variant | "default" | "default" | "alternative" | "heavy"Determines the appearance of the combobox. |
size | "md" | "sm" | "md" | "lg"Combobox height. |
width | "xs" | "4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "100%"Combobox width. |
popoverWidth | undefined | "4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg"The dropdown width. If not provided, the select width will be used. |
onChange | — | (value: OptionValue | undefined) => voidCallback for when user selects a different option or clears the selection. |
onCreateOption | — | (inputValue: string) => Promise<void> | voidCallback for creating a new option. It can be async. |
onClose | — | () => voidCallback for when user closes the select. |
onOpen | — | () => voidCallback for when user opens the select. |
onSearchUpdate | — | (inputValue: string) => voidCallback for when user changes the input value. |
valueLabel | — | (option: Option) => stringFunction to format a selected option's label. If not provided, `label` field will be used as a label. |
| Name | Default | Description |
|---|---|---|
isDisabled | — | booleanDetermines if combobox is disabled. |
isLoading | — | booleanIndicates that options are being loaded. |
isInvalid | — | booleanIndicates that combobox is in invalid state. |
isClearable | false | booleanDetermines if selection can be cleared. |
isOptionDisabled | — | (option: Option) => boolean | stringFunction to determine whether an option should be disabled. If a string is returned, it will be used as a disabled message. |
emptyOptionsMessage | "No options" | stringText to show inside a dropdown when there are no options. |
disableSortingAndFiltering | false | booleanDetermines if the options should be sorted and filtered internally. |
optionGroups | — | Array<{
label: string;
options: Option[];
}>Available options. `Option` is a generic, so type of options will be inferred. |
optionLabel | — | (option: Option) => stringFunction to extract label from an option. If it's not provided, `label` field will be used as a label. |
optionValue | — | (option: Option) => OptionValueFunction to extract value from an option. If it's not provided, `value` field will be used as a value. |
optionDescription | — | (option: Option) => stringFunction to extract description from an option. If it's not provided, `description` field will be used as a label. |
optionAccessories | — | SelectOptionAccessoriesGetter<Option>Function to show an accessory view near the option label. |
placeholder | — | stringText to show inside combobox when no option is selected. |
removePortal | false | booleanDetermines if the select dropdown should be rendered in a portal. |
renderInputInControl | true | booleanDetermines if the input should be rendered in the control. |
showPlaceholderIcon | false | booleanDetermines if the placeholder icon should be shown. Only available when optionAccessories is defined. |
size | "md" | "sm" | "md" | "lg"Combobox height. |
value | — | OptionValue | undefinedSelected option. |
variant | "default" | "default" | "alternative" | "heavy"Determines the appearance of the combobox. |
width | "xs" | "4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "100%"Combobox width. |
popoverWidth | undefined | "4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg"The dropdown width. If not provided, the select width will be used. |
onChange | — | (value: OptionValue | undefined) => voidCallback for when user selects a different option or clears the selection. |
onSearchUpdate | — | (inputValue: string) => voidCallback for when user changes the input value. |
valueLabel | — | (option: Option) => stringFunction to format a selected option's label. If not provided, `label` field will be used as a label. |
comboboxRef | — | RefObject<HTMLInputElement>Reference to the comboBox element. |