Sections

Components

Utilities

Forms

Hooks

useIsMobile

Combobox

Copy Markdown

Displays a searchable list of options.

Docs API

PreviewCode

Installation#

CLIManual

pnpmbunnpmyarn

pnpm dlx shadcn@latest add @shark/combobox

Anatomy#

Combobox
  ├── ComboboxInput
  └── ComboboxContent
      ├── ComboboxEmpty
      └── ComboboxList
        └── ComboboxGroup
          ├── ComboboxGroupLabel
          └── ComboboxItem

Usage#

import { useFilter, useListCollection } from "@ark-ui/react";
import {
  Combobox,
  ComboboxContent,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox";

const { contains } = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems: [
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
  ],
  filter: contains,
});

<Combobox
  collection={collection}
  onInputValueChange={({ inputValue }) => filter(inputValue)}
>
  <ComboboxInput placeholder="Select an option" />
  <ComboboxContent>
    <ComboboxList>
      {items.map((item) => (
        <ComboboxItem item={item} key={item.value}>
          {item.label}
        </ComboboxItem>
      ))}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Controlled#

Control the selected value with inputValue and onValueChange props.

PreviewCode

Selected: banana

Size#

Small#

PreviewCode

Medium#

PreviewCode

Large#

PreviewCode

States#

Invalid#

PreviewCode

Disabled#

PreviewCode

Examples#

Auto highlight#

Automatically highlight the first matching item as the user types.

PreviewCode

Group#

PreviewCode

With Field#

Use Combobox with Field components to style the combobox with the field components.

PreviewCode

Country

We'll use this for shipping estimates

Scrollable#

PreviewCode

Multiple#

Enable multiple selection by setting the multiple prop to Combobox.

PreviewCode

With clear button#

Pass showClear to ComboboxInput to show a clear button.

PreviewCode

With start icon#

PreviewCode

API Reference#

Combobox#

Root component.

Prop	Type	Default
`collection`	`ListCollection<T>`	required
`value`	`string	string[]`
`defaultValue`	`string	string[]`
`onValueChange`	`(details: ValueChangeDetails<T>) => void`	-
`onInputValueChange`	`(details: InputValueChangeDetails) => void`	-
`multiple`	`boolean`	`false`
`disabled`	`boolean`	-
`openOnClick`	`boolean`	`true`
`lazyMount`	`boolean`	`true`
`unmountOnExit`	`boolean`	`true`
`className`	`string`	-

ComboboxControl#

Optional wrapper for custom layouts.

Prop	Type	Default
`className`	`string`	-
`asChild`	`boolean`	-

ComboboxInput#

Input with dropdown trigger and optional clear button. Combines search and selection.

Prop	Type	Default
`size`	`"sm"	"md"
`showTrigger`	`boolean`	`true`
`showClear`	`boolean`	`false`
`disabled`	`boolean`	-
`className`	`string`	-

ComboboxTrigger#

Opens the dropdown on click.

Prop	Type	Default
`className`	`string`	-
`asChild`	`boolean`	-

ComboboxClear#

Button to clear the input value.

Prop	Type	Default
`asChild`	`boolean`	-

ComboboxContent#

Holds the dropdown options. Displayed in a portal.

Prop	Type	Default
`className`	`string`	-
`asChild`	`boolean`	-

ComboboxList#

Wraps the list of options. Use with collection.

Prop	Type	Default
`className`	`string`	-
`asChild`	`boolean`	-

ComboboxItem#

A single selectable option.

Prop	Type	Default
`item`	`T`	required
`className`	`string`	-
`asChild`	`boolean`	-

ComboboxGroup#

Groups related options under an optional heading.

Prop	Type	Default
`heading`	`string	ReactNode`
`className`	`string`	-
`asChild`	`boolean`	-

ComboboxGroupLabel#

Label for an option group.

Prop	Type	Default
`className`	`string`	-
`asChild`	`boolean`	-

ComboboxEmpty#

Shown when no options match the current filter. Use for empty state.

Prop	Type	Default
`className`	`string`	-
`children`	`ReactNode`	`No results found.`

For a complete list of props, see the Ark UI documentation.

[

Color Picker ](/docs/components/color-picker)[

Command ](/docs/components/command)

On This Page

Installation Anatomy Usage Controlled Size Small Medium Large States Invalid Disabled Examples Auto highlight Group With Field Scrollable Multiple With clear button With start icon API Reference Combobox ComboboxControl ComboboxInput ComboboxTrigger ComboboxClear ComboboxContent ComboboxList ComboboxItem ComboboxGroup ComboboxGroupLabel ComboboxEmpty