This library is still in development and is available only for internal usage at VTEX.
Skip to main content

Combobox

Version: 0.132.0

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

Loading...

Multiple

Loading...

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

Loading...

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.

Loading...

Custom rendering for i18n

You can use custom item rendering as a way of implementing internationalization for each option.

Loading...

Async

You can use the deferredValue and setMatches to handle searches in async environments.

Loading...

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.

Loading...

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.

Loading...

TODOs

Features and fixes scheduled for this component:

  • Support to render images and icons in items
  • Review translations

Props

useComboboxState

NameTypeDescriptionRequiredDefault
timeoutMsnumberTimeout of the deferredValue🚫-
listItemType[]List of items🚫-
getOptionValue(item: ItemType) => stringFunction 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) => stringFunction 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:

NameTypeDescription
valuestringCurrent input value
setLoadingReact.SetState<string>Set the value
deferredValuestringCurrent input value delayed by a defined timeoutMs
matchesItemType[]List of items that were a match for the current input search
setMatchesReact.SetState<ItemType[]>Set matches value
selectedItemItemTypeCurrently selected item, this props contains the full object, and not just the string value
setSelectedItem(arg: ItemType) => voidSet selected item value
setLoadingReact.SetState<boolean>Set loading state
setErrorReact.SetState<boolean>Set error state
getOptionValue(item: ItemType) => stringSame as the one passed to the hook
renderOption(item: ItemType) => stringSame as the one passed to the hook

useComboboxMultipleState

It extends the useComboboxState props, and:

NameTypeDescriptionRequiredDefault
shouldClearOnSelectbooleanIf should clear the text input on select an item🚫-
defaultSelectedItemType[]List of items that are selected by default🚫-
renderTag(item: ItemType) => ReactNodeFunction that controls what's rendered inside tag🚫copies renderOption prop's value

ComboboxMultipleState

The hooks return ComboboxMultipleState, which extends ComboboxState and additionally has:

NameTypeDescription
selectedItemsItemType[]List of selected items
setSelectedItemsSetStateAction<ItemType[]>Setter for selected items
unselect(value: string) => voidUnselect an item with this value
clearSelected() => voidClear the selected list
select(item: ItemType) => voidAdds inputed item to selected list
unselect(item: ItemType) => voidRemoves inputed item from selected list
renderTag(item: ItemType) => ReactNodeSame as the one inputed to hook
onChange(item: ItemType) => voidFunction that toggles if item is selected
isSelected(item: ItemType) => booleanFunction which returns selected status for an item

ComboboxField & ComboboxMultipleField

NameTypeDescriptionRequiredDefault
stateComboboxState or ComboboxMultipleStateRequired state-
labelstringRequired label-
idstringRequired id-
csxStyleObjectCustom styles🚫{}

ComboboxPopover & ComboboxMultiplePopover

NameTypeDescriptionRequiredDefault
stateComboboxState or ComboboxMultipleStateRequired state-
onRetry() => voidFunction to be called on retry🚫-
csxStyleObjectCustom styles🚫{}