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

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	🚫	{}