Fidely UI v1 beta is now available!. 🚀

Combobox

A single input field that combines the functionality of select and input.

Usage

import { Combobox } from '@fidely-ui/react'
<Combobox.Root>
  <Combobox.Label />
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.IndicatorGroup>
      <Combobox.ClearTrigger />
      <Combobox.Trigger />
    </Combobox.IndicatorGroup>
  </Combobox.Control>

  <Combobox.Positioner>
    <Combobox.Content>
      <Combobox.Empty />
      <Combobox.Item />

      <Combobox.ItemGroup>
        <Combobox.ItemGroupLabel />
        <Combobox.Item />
      </Combobox.ItemGroup>
    </Combobox.Content>
  </Combobox.Positioner>
</Combobox.Root>

Examples

Sizes

Use the size prop to adjust the size of the Select component.

Open on Click

Use the openOnClick prop to open the Combobox when the user clicks on the input.

Custom Objects

By default, the Combobox collection expects an array of objects with label and value properties. In some cases, you may need to deal with custom objects.

Use the itemToString and itemToValue props to map the custom object to the required interface.

const items = [
  { name: 'JavaScript', id: 'js' },
  { name: 'TypeScript', id: 'ts' },
  { name: 'Python', id: 'py' },
  { name: 'Go', id: 'go' },
  { name: 'Rust', id: 'rs' },
]

const { contains } = useFilter({ sensitivity: 'base' })

const { collection } = useListCollection({
  initialItems: items,
  itemToString: (item) => item.name,
  itemToValue: (item) => item.id,
  filter: contains,
})

With Persona

Use Combobox with Persona component

Minimum Characters

Use the openOnChange prop to set a minimum number of characters before filtering the list.

<Combobox.Root openOnChange={(e) => e.inputValue.length > 2} />

Disabled

Pass the disabled prop to the Combobox.Root to disable the entire combobox.

Disabled Item

Disable specific items in the dropdown, add the disabled prop to the collection item.

const items = [
  { label: 'Item 1', value: 'item-1', disabled: true },
  { label: 'Item 2', value: 'item-2' },
]

const { collection } = useListCollection({
  initialItems: items,
})

Store

An alternative way to control the Combobox component is to use the Combobox.RootProvider component and the useCombobox store hook.

import { Combobox, useCombobox } from '@fidely-ui/react'

function ComboboxDemo() {
  const combobox = useCombobox()

  return (
    <Combobox.RootProvider value={combobox}>{/* ... */}</Combobox.RootProvider>
  )
}

This way you can access the combobox state and methods from outside the combobox.

Limit Large Datasets

The recommended way of managing large lists is to use the limit property on the useListCollection hook. This will limit the number of rendered items in the DOM to improve performance.

Within Dialog

To use the Combobox within a dialog component, avoid wrapping the Combobox.Positioner within the Portal.

;-(
  <Portal>
    <Combobox.Positioner>
      <Combobox.Content>{/* ... */}</Combobox.Content>
    </Combobox.Positioner>
    -
  </Portal>
)

If you use a Dialog and have set scrollBehavior="inside", you need to:

  • Set the combobox positioning to fixed to avoid the combobox from being clipped by the dialog.
  • Set hideWhenDetached to true to hide the combobox when the trigger is scrolled out of view.
<Combobox.Root positioning={{ strategy: 'fixed', hideWhenDetached: true }}>
  {/* ... */}
</Combobox.Root>

Props

Root

PropTypeDefaultDescription
allowCustomValueboolean—Whether to allow typing custom values in the input.
asReact.ElementType—The underlying element to render.
asChildboolean—Uses the provided child element as the rendered element, merging its props and behavior.
autoFocusboolean—Whether to autofocus the input on mount.
closeOnSelectboolean—Whether to close the combobox when an item is selected.
collectionListCollection<T>—The collection of items.
compositebooleantrueWhether the combobox is composed with other composite widgets like tabs.
defaultHighlightedValuestring—The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.
defaultInputValuestring—The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input.
defaultOpenboolean—The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.
defaultValuestring[][]The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items.
disabledboolean—Whether the combobox is disabled.
disableLayerboolean—Whether to disable registering this a dismissable layer.
formstring—The associate form of the combobox.
highlightedValuestring—The controlled highlighted value of the combobox.
idstring—The unique identifier of the component.
immediateboolean—Whether to synchronize the present change immediately or defer it to the next frame.
inputBehavior'none' &#124; 'autohighlight' &#124; 'autocomplete'noneDefines the auto-completion behavior of the combobox. • autohighlight: The first focused item is highlighted as the user types • autocomplete: Navigating the listbox with the arrow keys selects the item and updates the input.
inputValuestring—The controlled value of the combobox's input.
invalidboolean—Whether the combobox is invalid.
loopFocusbooleantrueWhether to loop the keyboard navigation through the items.
multipleboolean—Whether to allow multiple selection. Good to know: When multiple is true, the selectionBehavior is automatically set to clear. It is recommended to render the selected items in a separate container.
namestring—The name attribute of the combobox's input. Useful for form submission.
Maps(details: NavigateDetails) => void—Function to navigate to the selected item.
onFocusOutside(event: FocusOutsideEvent) => void—Function called when the focus is moved outside the component.
onInputValueChange(details: OpenChangeDetails) => void—Function called when the input value changes.
onPointerDownOutside(event: PointerDownOutsideEvent) => void—Function called when the pointer is pressed down outside the component.
onSelect(details: SelectionDetails) => void—Function called when an item is selected.
onValueChange(details: ValueChangeDetails<T>) => void—Function called when a new item is selected.
openboolean—The controlled open state of the combobox.
openOnChangeboolean &#124; ((details: InputValueChangeDetails) => boolean)trueWhether to open the combobox when the input value changes.
openOnClickbooleanfalseWhether to open the combobox popup on initial click on the input.
openOnKeyPressbooleantrueWhether to open the combobox on arrow key press.
placeholderstring—The placeholder text of the combobox's input.
positioningPositioningOptions{ placement: "bottom-start" }The positioning options to dynamically position the menu.
requiredboolean—Whether the combobox is required.
selectionBehavior'replace' &#124; 'clear' &#124; 'preserve''replace'The behavior of the combobox input when an item is selected.
size'xs' &#124; 'sm' &#124; 'md' &#124; 'lg'mdThe size of the component.
translationsIntlTranslations—Specifies the localized strings that identifies the accessibility elements and their states.
unmountOnExitbooleanfalseWhether to unmount on exit.
valuestring[]—The controlled value of the combobox's selected items.

Item

PropTypeDefaultDescription
asChildboolean—Uses the provided child element as the rendered element, merging behavior.
itemany—The item to render.
persistFocusboolean—Whether hovering outside should clear the highlighted state.
asboolean—The underlying element to render..

On this page