Combobox

Usage

import { Combobox } from "@chakra-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>

To setup combobox, you might need to import the following hooks:

• useListCollection: Used to manage the list of items in the combobox, providing helpful methods for filtering and mutating the list.

• useFilter: Used to provide the filtering logic for the combobox based on Intl.Collator APIs.

Examples

Basic

The basic combobox provides a searchable dropdown with single selection.

Sizes

Pass the size prop to the Combobox.Root to change the size of the combobox.

Variants

Pass the variant prop to the Combobox.Root to change the appearance of the combobox.

Multiple

Pass the multiple prop to the Combobox.Root to enable multiple selection. This allows users to select multiple items from the list.

Async Loading

Here's an example of loading the collection asynchronously as users type, perfect for API-driven search interfaces.

Highlight Matching Text

Here's an example of composing the Combobox.Item and Highlight components to highlight matching text in search results.

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 = [
  { country: "United States", code: "US", flag: "🇺🇸" },
  { country: "Canada", code: "CA", flag: "🇨🇦" },
  { country: "Australia", code: "AU", flag: "🇦🇺" },
  // ...
]

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

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

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} />

Field

Compose the Combobox component with the Field component to wrap the combobox in a form field. Useful for form layouts.

Form + Custom Object

When working with custom objects in forms, you often need to submit the programmatic value rather than the display value. This example shows how to combine custom object mapping with form submission using a hidden input.

The key is using itemToValue to define what gets submitted, while itemToString controls what users see. A hidden input captures the programmatic value for form submission.

Hook Form

This example demonstrates how to integrate the Combobox with React Hook Form using the Controller component. The form automatically receives the item's value property without needing a hidden input.

Users see "React" but the form receives "react".

Disabled State

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,
  // ...
})

Input Group

Combine with InputGroup to add icons or other elements.

Invalid

Pass the invalid prop to the Combobox.Root to show the error state.

Controlled Value

Use the value and onValueChange props to control the combobox's value programmatically.

Store

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

import { Combobox, useCombobox } from "@chakra-ui/react"

function Demo() {
  const combobox = useCombobox()

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

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

Controlled Open

Use the open and onOpenChange props to control the combobox's open state programmatically.

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.

Virtualization

Alternatively, you can leverage virtualization from the @tanstack/react-virtual package to render large datasets efficiently.

Links

Use the asChild prop to render the combobox items as links.

For custom router links, you can customize the navigate prop on the Combobox.Root component.

Here's an example of using the Tanstack Router.

import { Combobox } from "@chakra-ui/react"
import { useNavigate } from "@tanstack/react-router"

function Demo() {
  const navigate = useNavigate()
  return (
    <Combobox.Root
      navigate={({ href }) => {
        navigate({ to: href })
      }}
    >
      {/* ... */}
    </Combobox.Root>
  )
}

Rehydrate Value

In some cases, where a combobox has a defaultValue but the collection is not loaded yet, here's an example of how to rehydrate the value and populate the input value.

Custom Item

Customize the appearance of items in the dropdown with your own components.

PreviewCode

Stackblitz

Search and select car brands

Custom Filter

Here's an example of a custom filter that matches multiple properties of an item.

Custom Animation

To customize the animation of the combobox, pass the _open and _closed prop to the Combobox.Content component.

Within Dialog

To use the combobox within a dialog or popover 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>

Creatable

Here's an example of how to allow users to create new options by typing values that don't exist in the list. It uses the useCombobox and Combobox.RootProvider components for smoother integration and management.

Props

Root

Item

Explorer

Explore the Combobox component parts interactively. Click on parts in the sidebar to highlight them in the preview.