Combobox

Import

import { Combobox, ComboItemWithIndicator, ComboItemText } from '@cerberus/react'

Usage

The Combobox is an abracted API that combines multiple primitives into a single root component. You combine this with the useStatefulCollection hook to create a filterable select component.

With Start Icon

To add an icon to the start position of the input, use the startIcon prop to pass in your icon of choice.

Sizes

The Combobox component supports sizes: sm to lg. The default is md.

With Field

Wrap the Combobox component with the Field component to add additional functionality such as error and helper text when using it in a form.

Context

Access the combobox's state with ComboboxContext or the useComboboxContext hook—useful for displaying the selected value or building custom UI.

Note

Since combobox is an abstracted API, you'll need to build your own to obtain the context as we do in the example below.

Grouped Items

To group items, use the ComboItemGroup component (not ComboboxItemGroup).

Async Loading

Combine the collection with a query to load data asynchronously with signal-based speed.

Highlight Matching Text

Combine the ComboItemText component with the Highlight component to highlight matching text in the dropdown.

Creatable

Allow users to create new options when their search doesn't match any existing items. This is useful for tags, categories, or other custom values.

Customizing

Guides

Router Links

Customize the navigate prop on Combobox to integrate with your router. Using Tanstack Router:

import { Combobox } from '@cerberus/react'
import { useNavigate } from '@tanstack/react-router'
 
function Demo() {
  const navigate = useNavigate()
  return (
    <Combobox
      navigate={(e) => {
        navigate({ to: e.node.href })
      }}
    >
      {/* ... */}
    </Combobox>
  )
}

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 = [
  { country: 'United States', code: 'US', flag: '🇺🇸' },
  { country: 'Canada', code: 'CA', flag: '🇨🇦' },
  { country: 'Australia', code: 'AU', flag: '🇦🇺' },
  // ...
]
 
const { collection } = useListCollection({
  initialItems: items,
  itemToString: (item) => item.country,
  itemToValue: (item) => item.code,
})

Type Safety

The ComboboxRootProps type enables you to create typed wrapper components that maintain full type safety for collection items.

const Combobox = (props: ComboboxRootProps) => {
  return <CerbyCombobox {...props}>{/* ... */}</CerbyCombobox>
}

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.

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

Available Size

The following css variables are exposed to the ComboboxPositioner which you can use to style the ComboboxContent.

/* width of the combobox control */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;

For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following:

[data-scope='combobox'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}

Primitives

You can utilize the primitive components or the css prop to customize the Combobox.

API

Combobox

The Combobox component is an abstraction of our primitives and accepts the following props:

The Combobox component also accepts all the props of the ComboboxRoot primitive props

ItemWithIndicator

The ItemWithIndicator component is an abstraction of our primitives and accepts all the props of the ComboboxItem primitive props

ComboItemGroup

The ComboItemGroup component is an abstraction of our primitives and accepts the following props:

The ComboItemGroup component is an abstraction of our primitives and accepts all the props of the ComboboxItemGroup primitive props

Primitive API

Root Props

Root Data Attributes:

ClearTrigger Props:

ClearTrigger Data Attributes:

Content Props:

Content Data Attributes:

Content CSS Variables:

Control Props:

Control Data Attributes:

Input Props:

Input Data Attributes:

ItemGroupLabel Props:

ItemGroup Props:

ItemGroup Data Attributes:

ItemIndicator Props:

ItemIndicator Data Attributes:

Item Props:

Item Data Attributes:

ItemText Props:

ItemText Data Attributes:

Label Props:

Label Data Attributes:

List Props:

List Data Attributes:

Positioner Props:

Positioner CSS Variables:

RootProvider Props:

Trigger Props:

Trigger Data Attributes:

Hooks

useStatefulCollection

The useStatefulCollection function is a utility hook that creates a collection of options and filters the list based on the user input.

Returns

Parts

The ComboboxParts API is an Object containing the full family of components.

Note

It is best to only use the ComboboxParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.