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.
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 an additional accessory view before the label. You can show an image using an image accessory. This is useful for showing logos when selecting sources or destinations, for example.
Icons can be accessories too.
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 | — | boolean Determines if combobox is disabled. |
isLoading | — | boolean Indicates that options are being loaded. |
isInvalid | — | boolean Indicates that combobox is in invalid state. |
isClearable | false | boolean Determines if selection can be cleared. |
isOptionDisabled | — | (option: Option) => boolean Function to determine whether an option should be disabled. |
emptyOptionsMessage | "No options" | string Text to show inside a dropdown when there are no options. |
supportsCreatableOptions | — | boolean Determines if user is allowed to create a new option, if it's not present already. |
createOptionMessage | "Create "[input value]"" | (inputValue: string) => string Text to show inside dropdown when creating a new option. |
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) => string Function to extract label from an option. If it's not provided, `label` field will be used as a label. |
optionDescription | — | (option: Option) => string Function to extract description from an option. If it's not provided, `description` field will be used as a label. |
optionValue | — | (option: Option) => OptionValue Function to extract value from an option. If it's not provided, `value` field will be used as a value. |
optionAccessory | — | (option: Option) => SelectOptionAccessoryType | undefined Function to show an accessory view near the option label. |
placeholder | — | string Text to show inside combobox when no option is selected. |
removePortal | false | boolean Determines if the select dropdown should be rendered in a portal. |
value | — | OptionValue | undefined Selected 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) => void Callback for when user selects a different option or clears the selection. |
onCreateOption | — | (inputValue: string) => Promise<void> | void Callback for creating a new option. It can be async. |
onClose | — | () => void Callback for when user closes the select. |
onOpen | — | () => void Callback for when user opens the select. |
valueLabel | — | (option: Option) => string Function to format a selected option's label. If not provided, `label` field will be used as a label. |
Name | Default | Description |
---|---|---|
isDisabled | — | boolean Determines if combobox is disabled. |
isLoading | — | boolean Indicates that options are being loaded. |
isInvalid | — | boolean Indicates that combobox is in invalid state. |
isClearable | false | boolean Determines if selection can be cleared. |
isOptionDisabled | — | (option: Option) => boolean Function to determine whether an option should be disabled. |
emptyOptionsMessage | "No options" | string Text to show inside a dropdown when there are no options. |
optionGroups | — | Array<{
label: string;
options: Option[];
}> Available options. `Option` is a generic, so type of options will be inferred. |
optionLabel | — | (option: Option) => string Function to extract label from an option. If it's not provided, `label` field will be used as a label. |
optionValue | — | (option: Option) => OptionValue Function to extract value from an option. If it's not provided, `value` field will be used as a value. |
optionDescription | — | (option: Option) => string Function to extract description from an option. If it's not provided, `description` field will be used as a label. |
optionAccessory | — | (option: Option) => SelectOptionAccessoryType | undefined Function to show an accessory view near the option label. |
placeholder | — | string Text to show inside combobox when no option is selected. |
removePortal | false | boolean Determines if the select dropdown should be rendered in a portal. |
size | "md" | "sm" | "md" | "lg" Combobox height. |
value | — | OptionValue | undefined Selected 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) => void Callback for when user selects a different option or clears the selection. |
valueLabel | — | (option: Option) => string Function 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. |