Combobox
Usage
import {
experimental_ComboboxField as ComboboxField,
experimental_ComboboxPopover as ComboboxPopover,
experimental_useComboboxState as useComboboxState,
experimental_ComboboxMultipleField as ComboboxMultipleField,
experimental_ComboboxMultiplePopover as ComboboxMultiplePopover,
experimental_useComboboxMultipleState as useComboboxMultipleState,
} from '@vtex/admin-ui'
function Single() {
const combobox = useComboboxState({
list: [],
})
return (
<>
<ComboboxField id="id" label="Label" state={combobox} />
<ComboboxPopover state={combobox} />
</>
)
}
function Multiple() {
const comboboxMultiple = useComboboxMultipleState({
list: [],
})
return (
<>
<ComboboxMultipleField id="id" label="Label" state={comboboxMultiple} />
<ComboboxMultiplePopover state={comboboxMultiple} />
</>
)
}
Examples
Single
Multiple
Custom rendering
You can use objects instead of strings for your combobox's list and define a custom rendering function for each option. For this you must also define a getOptionValue
function (for converting the object shape into a unique string value),
a renderOption
function which should return a ReactNode that represents this object visually. If you don't define these 2 functions and you use objects on your list you will get an unexpected behavior.
The value obtained by the getOptionValue
function will be the one considered when performing the search based on the user input.
Input example
list: [
{ value: 'Brazil', flag: '🇧🇷' },
{ value: 'France', flag: '🇫🇷' },
{ value: 'UK', flag: '🇬🇧' },
{ value: 'Colombia', flag: '🇨🇴' },
],
getOptionValue: (item) => item.value,
renderOption: (item) => (
<>
{item.value}
{item.flag}
</>
Basic custom rendering example
Custom rendering for combobox multiple
When using comboboxMultiple you can also define a custom rendering function specifically for the tags, if you don't set it, renderOption will be used.
Custom rendering for i18n
You can use custom item rendering as a way of implementing internationalization for each option.
Async
You can use the deferredValue
and setMatches
to handle searches in async environments.
Handling states
The loading
and error
states can be toggled programmatically with setLoading
and setError
. Use these functions to interact with your data-fetching library.
I18n
The combobox has default translations for the popover strings. Since the label can vary, you should handle this translation. Wrap your app with the I18nProvider to configure the locale.
TODOs
Features and fixes scheduled for this component:
- Support to render images and icons in items
- Review translations
Props
useComboboxState
Name | Type | Description | Required | Default |
---|---|---|---|---|
timeoutMs | number | Timeout of the deferredValue | 🚫 | - |
list | ItemType[] | List of items | 🚫 | - |
getOptionValue | (item: ItemType) => string | Function that transforms item shape into a string value, no need to use it on string[] lists | 🚫 | by default it returns the item value, stringified if it is not string |
renderOption | (item: ItemType) => string | Function for transforming item shape into renderable node, no need to use it on string[] lists | 🚫 | by default it returns the item value, stringified if it is not string |
ComboboxState
The hooks return the ComboboxState, with the values:
Name | Type | Description |
---|---|---|
value | string | Current input value |
setLoading | React.SetState<string> | Set the value |
deferredValue | string | Current input value delayed by a defined timeoutMs |
matches | ItemType[] | List of items that were a match for the current input search |
setMatches | React.SetState<ItemType[]> | Set matches value |
selectedItem | ItemType | Currently selected item, this props contains the full object, and not just the string value |
setSelectedItem | (arg: ItemType) => void | Set selected item value |
setLoading | React.SetState<boolean> | Set loading state |
setError | React.SetState<boolean> | Set error state |
getOptionValue | (item: ItemType) => string | Same as the one passed to the hook |
renderOption | (item: ItemType) => string | Same as the one passed to the hook |
useComboboxMultipleState
It extends the useComboboxState
props, and:
Name | Type | Description | Required | Default |
---|---|---|---|---|
shouldClearOnSelect | boolean | If should clear the text input on select an item | 🚫 | - |
defaultSelected | ItemType[] | List of items that are selected by default | 🚫 | - |
renderTag | (item: ItemType) => ReactNode | Function that controls what's rendered inside tag | 🚫 | copies renderOption prop's value |
ComboboxMultipleState
The hooks return ComboboxMultipleState
, which extends ComboboxState
and additionally has:
Name | Type | Description |
---|---|---|
selectedItems | ItemType[] | List of selected items |
setSelectedItems | SetStateAction<ItemType[]> | Setter for selected items |
unselect | (value: string) => void | Unselect an item with this value |
clearSelected | () => void | Clear the selected list |
select | (item: ItemType) => void | Adds inputed item to selected list |
unselect | (item: ItemType) => void | Removes inputed item from selected list |
renderTag | (item: ItemType) => ReactNode | Same as the one inputed to hook |
onChange | (item: ItemType) => void | Function that toggles if item is selected |
isSelected | (item: ItemType) => boolean | Function which returns selected status for an item |
ComboboxField & ComboboxMultipleField
Name | Type | Description | Required | Default |
---|---|---|---|---|
state | ComboboxState or ComboboxMultipleState | Required state | ✅ | - |
label | string | Required label | ✅ | - |
id | string | Required id | ✅ | - |
csx | StyleObject | Custom styles | 🚫 | {} |
ComboboxPopover & ComboboxMultiplePopover
Name | Type | Description | Required | Default |
---|---|---|---|---|
state | ComboboxState or ComboboxMultipleState | Required state | ✅ | - |
onRetry | () => void | Function to be called on retry | 🚫 | - |
csx | StyleObject | Custom styles | 🚫 | {} |