ContextQMD
Back to Shadcn Ui

Combobox

apps/v4/content/docs/components/base/combobox.mdx

latest5.5 KB
Original Source

<ComponentPreview styleName="base-nova" name="combobox-demo" description="A combobox with a list of frameworks." />

Installation

<CodeTabs> <TabsList> <TabsTrigger value="cli">Command</TabsTrigger> <TabsTrigger value="manual">Manual</TabsTrigger> </TabsList> <TabsContent value="cli">
bash
npx shadcn@latest add combobox
</TabsContent> <TabsContent value="manual"> <Steps className="mb-0 pt-2">

<Step>Install the following dependencies:</Step>

bash
npm install @base-ui/react

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="combobox" title="components/ui/combobox.tsx" styleName="base-nova" />

<Step>Update the import paths to match your project setup.</Step>

</Steps> </TabsContent> </CodeTabs>

Usage

tsx
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
tsx
const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function ExampleCombobox() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Custom Items

Use itemToStringValue when your items are objects.

tsx
import * as React from "react"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

type Framework = {
  label: string
  value: string
}

const frameworks: Framework[] = [
  { label: "Next.js", value: "next" },
  { label: "SvelteKit", value: "sveltekit" },
  { label: "Nuxt", value: "nuxt" },
]

export function ExampleComboboxCustomItems() {
  return (
    <Combobox
      items={frameworks}
      itemToStringValue={(framework) => framework.label}
    >
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(framework) => (
            <ComboboxItem key={framework.value} value={framework}>
              {framework.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Multiple Selection

Use multiple with chips for multi-select behavior.

tsx
import * as React from "react"

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
} from "@/components/ui/combobox"

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function ExampleComboboxMultiple() {
  const [value, setValue] = React.useState<string[]>([])

  return (
    <Combobox
      items={frameworks}
      multiple
      value={value}
      onValueChange={setValue}
    >
      <ComboboxChips>
        <ComboboxValue>
          {value.map((item) => (
            <ComboboxChip key={item}>{item}</ComboboxChip>
          ))}
        </ComboboxValue>
        <ComboboxChipsInput placeholder="Add framework" />
      </ComboboxChips>
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Examples

Basic

A simple combobox with a list of frameworks.

<ComponentPreview styleName="base-nova" name="combobox-basic" />

Multiple

A combobox with multiple selection using multiple and ComboboxChips.

<ComponentPreview styleName="base-nova" name="combobox-multiple" />

Clear Button

Use the showClear prop to show a clear button.

<ComponentPreview styleName="base-nova" name="combobox-clear" />

Groups

Use ComboboxGroup and ComboboxSeparator to group items.

<ComponentPreview styleName="base-nova" name="combobox-groups" />

Custom Items

You can render a custom component inside ComboboxItem.

<ComponentPreview styleName="base-nova" name="combobox-custom" />

Invalid

Use the aria-invalid prop to make the combobox invalid.

<ComponentPreview styleName="base-nova" name="combobox-invalid" />

Disabled

Use the disabled prop to disable the combobox.

<ComponentPreview styleName="base-nova" name="combobox-disabled" />

Auto Highlight

Use the autoHighlight prop to automatically highlight the first item on filter.

<ComponentPreview styleName="base-nova" name="combobox-auto-highlight" />

You can trigger the combobox from a button or any other component by using the render prop. Move the ComboboxInput inside the ComboboxContent.

<ComponentPreview styleName="base-nova" name="combobox-popup" />

Input Group

You can add an addon to the combobox by using the InputGroupAddon component inside the ComboboxInput.

<ComponentPreview styleName="base-nova" name="combobox-input-group" />

RTL

To enable RTL support in shadcn/ui, see the RTL configuration guide.

<ComponentPreview styleName="base-nova" name="combobox-rtl" direction="rtl" align="start" />

API Reference

See the Base UI documentation for more information.