Combobox

An input that filters a list of options as you type.

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

const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"] as const

export default function ComboboxDemo() {
  return (
    <Combobox items={typefaces}>
      <ComboboxInput placeholder="Select a typeface" aria-label="Typeface" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/combobox

Needs the arene setup first. Also adds Button, Input and Input Group.

Usage

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"]

export function Example() {
  return (
    <Combobox items={typefaces}>
      <ComboboxInput placeholder="Select a typeface" aria-label="Typeface" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Pass the options through items and render each one from the function child of ComboboxList. Base UI filters items against what is typed, so a list written as static children does not filter and ComboboxEmpty never shows.

Give the input an aria-label or a Label. There is no Field to name it.

Composition

Simple

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

With chips

Combobox
├── ComboboxChips
│   ├── ComboboxValue
│   │   └── ComboboxChip
│   └── ComboboxChipsInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        └── ComboboxItem

With groups

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        └── ComboboxGroup
            ├── ComboboxSeparator
            ├── ComboboxLabel
            └── ComboboxCollection
                └── ComboboxItem

Custom items

Pass itemToStringLabel when the items are objects. The filter matches against its result, and the input shows it once an item is picked. Items shaped { value, label } need neither.

type Typeface = { label: string; value: string }

const typefaces: Typeface[] = [
  { label: "Geist", value: "geist" },
  { label: "Inter", value: "inter" },
  { label: "Manrope", value: "manrope" },
]

export function Example() {
  return (
    <Combobox items={typefaces} itemToStringLabel={(typeface: Typeface) => typeface.label}>
      <ComboboxInput placeholder="Select a typeface" aria-label="Typeface" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(typeface: Typeface) => (
            <ComboboxItem key={typeface.value} value={typeface}>
              {typeface.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Basic

A single input over a flat list.

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

const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"] as const

export default function ComboboxBasic() {
  return (
    <Combobox items={typefaces}>
      <ComboboxInput placeholder="Select a typeface" aria-label="Typeface" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Multiple

Set multiple and swap the input for ComboboxChips. The chosen values render as ComboboxChips from the function child of ComboboxValue, and ComboboxChipsInput filters what is left.

import { Fragment } from "react"
import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
  useComboboxAnchor,
} from "@/components/ui/combobox"
import { widths } from "@/theme/widths"

const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"] as const

export default function ComboboxMultiple() {
  const anchor = useComboboxAnchor()

  return (
    <Combobox multiple autoHighlight items={typefaces} defaultValue={[typefaces[0]]}>
      <ComboboxChips ref={anchor} xstyle={widths.xs}>
        <ComboboxValue>
          {(values: string[]) => (
            <Fragment>
              {values.map((value) => (
                <ComboboxChip key={value}>{value}</ComboboxChip>
              ))}
              <ComboboxChipsInput placeholder="Add typeface" aria-label="Typefaces" />
            </Fragment>
          )}
        </ComboboxValue>
      </ComboboxChips>
      <ComboboxContent anchor={anchor}>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Give ComboboxChips the ref from useComboboxAnchor and pass the same ref to ComboboxContent as anchor. Base UI otherwise positions against the input, which is only part of the frame.

Clear button

Set showClear on the input. The X is mounted only while there is a value, and it replaces the chevron while it is shown.

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

const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"] as const

export default function ComboboxClear() {
  return (
    <Combobox items={typefaces} defaultValue={typefaces[0]}>
      <ComboboxInput placeholder="Select a typeface" aria-label="Typeface" showClear />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Groups

Pass groups shaped { value, items } to items. Render each one as a ComboboxGroup with the group's items, a ComboboxLabel and a ComboboxCollection that renders the items.

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

const timezones = [
  {
    value: "Americas",
    items: [
      "(GMT-5) New York",
      "(GMT-8) Los Angeles",
      "(GMT-6) Chicago",
      "(GMT-5) Toronto",
      "(GMT-8) Vancouver",
      "(GMT-3) São Paulo",
    ],
  },
  {
    value: "Europe",
    items: [
      "(GMT+0) London",
      "(GMT+1) Paris",
      "(GMT+1) Berlin",
      "(GMT+1) Rome",
      "(GMT+1) Madrid",
      "(GMT+1) Amsterdam",
    ],
  },
  {
    value: "Asia/Pacific",
    items: [
      "(GMT+9) Tokyo",
      "(GMT+8) Shanghai",
      "(GMT+8) Singapore",
      "(GMT+4) Dubai",
      "(GMT+11) Sydney",
      "(GMT+9) Seoul",
    ],
  },
]

type Timezones = (typeof timezones)[number]

export default function ComboboxGroups() {
  return (
    <Combobox items={timezones}>
      <ComboboxInput placeholder="Select a timezone" aria-label="Timezone" />
      <ComboboxContent>
        <ComboboxEmpty>No timezones found.</ComboboxEmpty>
        <ComboboxList>
          {(group: Timezones, index: number) => (
            <ComboboxGroup key={group.value} items={group.items}>
              {index > 0 && <ComboboxSeparator />}
              <ComboboxLabel>{group.value}</ComboboxLabel>
              <ComboboxCollection>
                {(item: string) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxCollection>
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Filtering drops a group that has no match left, so a ComboboxSeparator goes inside the group rather than between groups. Render it before every group but the first.

Custom items

Render anything inside ComboboxItem. The tick stays at the trailing edge.

import * as stylex from "@stylexjs/stylex"
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
import { VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"

type Country = { code: string; label: string; continent: string }

const countries: Country[] = [
  { code: "ar", label: "Argentina", continent: "South America" },
  { code: "au", label: "Australia", continent: "Oceania" },
  { code: "br", label: "Brazil", continent: "South America" },
  { code: "ca", label: "Canada", continent: "North America" },
  { code: "cn", label: "China", continent: "Asia" },
  { code: "eg", label: "Egypt", continent: "Africa" },
  { code: "fr", label: "France", continent: "Europe" },
  { code: "de", label: "Germany", continent: "Europe" },
  { code: "jp", label: "Japan", continent: "Asia" },
  { code: "ke", label: "Kenya", continent: "Africa" },
  { code: "mx", label: "Mexico", continent: "North America" },
  { code: "nz", label: "New Zealand", continent: "Oceania" },
  { code: "za", label: "South Africa", continent: "Africa" },
  { code: "gb", label: "United Kingdom", continent: "Europe" },
  { code: "us", label: "United States", continent: "North America" },
]

const styles = stylex.create({
  title: { whiteSpace: "nowrap", fontWeight: 500 },
})

export default function ComboboxCustom() {
  return (
    <Combobox items={countries} itemToStringLabel={(country: Country) => country.label}>
      <ComboboxInput placeholder="Search countries..." aria-label="Country" />
      <ComboboxContent>
        <ComboboxEmpty>No countries found.</ComboboxEmpty>
        <ComboboxList>
          {(country: Country) => (
            <ComboboxItem key={country.code} value={country}>
              <VStack gap={0.5}>
                <span {...stylex.props(styles.title)}>{country.label}</span>
                <Text size="xs" tone="muted">
                  {country.continent} ({country.code})
                </Text>
              </VStack>
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Invalid

Set invalid on Field to style its control, or aria-invalid on a bare control. The examples show both.

import { VStack } from "@/components/ui/stack"
import { Field, FieldLabel } from "@/components/ui/field"
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"] as const

function BareControl({ bare = false }: { bare?: boolean }) {
  return (
    <Combobox items={typefaces}>
      <ComboboxInput
        placeholder="Select a typeface"
        aria-label="Typeface"
        aria-invalid={bare || undefined}
      />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

export default function InvalidExample() {
  return (
    <VStack gap={5}>
      <BareControl bare />
      <Field invalid>
        <FieldLabel>Typeface</FieldLabel>
        <BareControl />
      </Field>
    </VStack>
  )
}

Disabled

Set disabled on Field to disable its control and dim its label, or on a bare control directly.

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

const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"] as const

export default function ComboboxDisabled() {
  return (
    <Field disabled>
      <FieldLabel>Typeface</FieldLabel>
      <Combobox items={typefaces}>
        <ComboboxInput placeholder="Select a typeface" />
        <ComboboxContent>
          <ComboboxEmpty>No items found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </Field>
  )
}

Auto highlight

Set autoHighlight on Combobox to highlight the first match as you type, so Enter picks it.

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

const typefaces = ["Geist", "Inter", "Manrope", "Source Serif", "JetBrains Mono"] as const

export default function ComboboxAutoHighlight() {
  return (
    <Combobox items={typefaces} autoHighlight>
      <ComboboxInput placeholder="Select a typeface" aria-label="Typeface" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Render a ComboboxTrigger as a Button and move ComboboxInput inside ComboboxContent, with showTrigger={false}. ComboboxValue shows the current value in the button.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxTrigger,
  ComboboxValue,
} from "@/components/ui/combobox"

type Country = { code: string; label: string }

const countries: Country[] = [
  { code: "", label: "Select country" },
  { code: "ar", label: "Argentina" },
  { code: "au", label: "Australia" },
  { code: "br", label: "Brazil" },
  { code: "ca", label: "Canada" },
  { code: "cn", label: "China" },
  { code: "eg", label: "Egypt" },
  { code: "fr", label: "France" },
  { code: "de", label: "Germany" },
  { code: "jp", label: "Japan" },
  { code: "ke", label: "Kenya" },
  { code: "mx", label: "Mexico" },
  { code: "nz", label: "New Zealand" },
  { code: "za", label: "South Africa" },
  { code: "gb", label: "United Kingdom" },
  { code: "us", label: "United States" },
]

const styles = stylex.create({
  trigger: { width: "16rem", justifyContent: "space-between", fontWeight: 400 },
})

export default function ComboboxPopup() {
  return (
    <Combobox items={countries} defaultValue={countries[0]}>
      <ComboboxTrigger render={<Button variant="outline" xstyle={styles.trigger} />}>
        <ComboboxValue />
      </ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput showTrigger={false} placeholder="Search" aria-label="Search countries" />
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item: Country) => (
            <ComboboxItem key={item.code} value={item}>
              {item.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Input group

ComboboxInput is an InputGroup, so an InputGroupAddon passed as its child renders inside the frame.

import {
  Combobox,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
} from "@/components/ui/combobox"
import { InputGroupAddon } from "@/components/ui/input-group"
import { GlobeIcon } from "@phosphor-icons/react/dist/csr/Globe"

const timezones = [
  {
    value: "Americas",
    items: ["(GMT-5) New York", "(GMT-8) Los Angeles", "(GMT-6) Chicago", "(GMT-5) Toronto"],
  },
  {
    value: "Europe",
    items: ["(GMT+0) London", "(GMT+1) Paris", "(GMT+1) Berlin", "(GMT+1) Rome"],
  },
  {
    value: "Asia/Pacific",
    items: ["(GMT+9) Tokyo", "(GMT+8) Shanghai", "(GMT+8) Singapore", "(GMT+11) Sydney"],
  },
]

type Timezones = (typeof timezones)[number]

export default function ComboboxInputGroup() {
  return (
    <Combobox items={timezones}>
      <ComboboxInput placeholder="Select a timezone" aria-label="Timezone">
        <InputGroupAddon>
          <GlobeIcon aria-hidden="true" />
        </InputGroupAddon>
      </ComboboxInput>
      <ComboboxContent>
        <ComboboxEmpty>No timezones found.</ComboboxEmpty>
        <ComboboxList>
          {(group: Timezones) => (
            <ComboboxGroup key={group.value} items={group.items}>
              <ComboboxLabel>{group.value}</ComboboxLabel>
              <ComboboxCollection>
                {(item: string) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxCollection>
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Combobox part of the same name and accepts its props. See the Base UI reference for the full list. Each styled part also takes xstyle and className. ComboboxList, ComboboxItem and ComboboxChip take style too. It is real inline CSS, merged over whatever their Base UI state resolves to.

Combobox

PropTypeDefault
itemsreadonly Item[] | readonly Group[]—
multiplebooleanfalse
valueItem | Item[] | null—
defaultValueItem | Item[] | null—
onValueChange(value, details) => void—
autoHighlightbooleanfalse
itemToStringLabel(item: Item) => string—
filter(item, query, toString) => boolean—
disabledbooleanfalse
namestring—

ComboboxInput

PropTypeDefault
showTriggerbooleantrue
showClearbooleanfalse
disabledbooleanfalse
aria-invalidboolean—

xstyle and className apply to the InputGroup frame, not the <input>. The popup anchors to the frame, so the popup is the frame's width, addons included.

ComboboxContent

PropTypeDefault
side"top" | "bottom" | "left" | "right" | "inline-start" | "inline-end""bottom"
sideOffsetnumber6
align"start" | "center" | "end""start"
alignOffsetnumber0
anchorElement | RefObject<Element>—

The popup is never narrower than 9rem and never taller than 18rem. The list inside scrolls.

ComboboxItem

PropTypeDefault
valueItem—
disabledbooleanfalse

ComboboxGroup

PropTypeDefault
itemsreadonly Item[]—

ComboboxChip

PropTypeDefault
showRemovebooleantrue

comboboxStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
contentThe popup box: width, radius, transition
listThe scrolling list and its padding
itemAn item's row, type and nested corner
itemHighlightedThe highlight fill and inset ring
itemDisabledThe dimmed, inert item
labelA group label
emptyThe empty message
separatorThe hairline between groups
chipsThe multi-select frame, ring and surface
chipOne chip
chipsInputThe bare input inside the chips frame

content carries no surface. The fill and its hairline ring come from popupSurface. It sets --arene-popup-radius, and item merges popupItem, so a row's corner is that radius less the list's inset. A highlighted item is itemHighlight and itemDisabled is disabled. chips is the frame's box, focusWithinRing, fieldSurface and the drop with the halo beside it on :focus-within, all from states in theme/states.ts.

Data attributes

AttributeOnEffect
data-slot="combobox-content"the popupPopup surface
data-side, data-alignthe popupBase UI writes them. data-side picks the slide direction
data-emptythe popupBase UI writes it when the filter leaves nothing
data-starting-style, data-ending-stylethe popupBase UI writes them while the popup animates in or out
data-slot="input-group"the input frameThe frame ComboboxInput renders
data-popup-openthe frame, inputBase UI writes it while the popup is open
data-slot="combobox-trigger"the chevronWhat interop.css hides beside a clear button
data-slot="combobox-clear"the clear buttonMounted only while there is a value
data-slot="combobox-item"an itemTargets items from a parent
data-highlighted, data-selectedan itemBase UI writes them
data-disabledan item, a chipBase UI writes it
data-slot="combobox-chips"the chips frameTargets the frame from a parent
data-slot="combobox-chip"a chipTargets a chip from a parent