Combobox

Ein filterbares Select mit Chips, Gruppen und asynchronen Ergebnissen, in einem Popup, das sich beim Tippen anpasst.

Fruit

"use client"

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

const fruits = [
  "Apple",
  "Apricot",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Grapefruit",
  "Kiwi",
  "Lychee",
  "Mango",
  "Orange",
  "Papaya",
  "Peach",
  "Pear",
  "Pineapple",
  "Plum",
  "Raspberry",
  "Strawberry",
  "Watermelon",
]

export function ComboboxDemo() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-demo">Fruit</Label>
      <Combobox items={fruits}>
        <ComboboxInput id="combobox-demo" placeholder="Select a fruit" />
        <ComboboxContent>
          <ComboboxEmpty>No fruit found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Installation

pnpm dlx shadcn@latest add https://hextaui.com/r/combobox.json

Fügt die Komponente, die HextaUI-Theme-Tokens und alle HextaUI-Komponenten hinzu, von denen sie abhängt.

Füge die Theme-Tokens zu deinem globalen CSS hinzu, falls du das noch nicht getan hast.

Installiere die Abhängigkeiten.

pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn

3
Kopiere den folgenden Code und füge ihn in dein Projekt ein.
components/ui/combobox.tsx
"use client" import * as React from "react" import { Combobox as ComboboxPrimitive } from "@base-ui/react/combobox" import { useDirection } from "@base-ui/react/direction-provider" import { IconCheck, IconChevronDown,
Passe die Importpfade an dein Projekt-Setup an.

Verwendung

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

const fruits = ["Apple", "Banana", "Cherry"]

<Combobox items={fruits}>
  <ComboboxInput placeholder="Select a fruit" />
  <ComboboxContent>
    <ComboboxEmpty>No fruit found.</ComboboxEmpty>
    <ComboboxList>
      {(item: string) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Übergib die Optionen an items und rendere jede mit einer Funktion in <ComboboxList />. Die Combobox filtert sie beim Tippen und rendert nur die Treffer. Objekte funktionieren auch: Ihr label wird im Input angezeigt und ihr value gesendet.

Komposition

Input

Tippe in das Feld, um die Liste zu filtern.

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

Button-Trigger

Ein Button zeigt den Wert, und das Suchfeld wandert in das Popup.

Combobox
├── ComboboxTrigger
│   └── ComboboxValue
└── ComboboxContent
    ├── ComboboxInput
    ├── ComboboxEmpty
    └── ComboboxList
        └── ComboboxItem

Chips

Mit multiple wird jeder ausgewählte Eintrag zu einem Chip vor dem Input.

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

Beispiele

Löschen-Button

showClear fügt einen Löschen-Button hinzu, der den Platz des Chevrons einnimmt, solange ein Wert vorhanden ist, sodass das Feld nie wächst.

"use client"

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

const fruits = [
  "Apple",
  "Apricot",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Grapefruit",
  "Kiwi",
  "Lychee",
  "Mango",
  "Orange",
  "Papaya",
  "Peach",
  "Pear",
  "Pineapple",
  "Plum",
  "Raspberry",
  "Strawberry",
  "Watermelon",
]

export function ComboboxWithClear() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-clear">Fruit</Label>
      <Combobox items={fruits} defaultValue="Mango">
        <ComboboxInput
          id="combobox-clear"
          placeholder="Select a fruit"
          showClear
        />
        <ComboboxContent>
          <ComboboxEmpty>No fruit found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Mit Icons

Icons in einem Eintrag werden automatisch dimensioniert und gedämpft. autoHighlight hebt den ersten Treffer beim Tippen hervor, sodass Enter ihn auswählt.

"use client"

import type * as React from "react"
import {
  IconBrandAngular,
  IconBrandNextjs,
  IconBrandReact,
  IconBrandSvelte,
  IconBrandVue,
} from "@tabler/icons-react"

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

type Framework = {
  value: string
  label: string
  icon: React.ComponentType<{ className?: string }>
}

const frameworks: Framework[] = [
  { value: "next", label: "Next.js", icon: IconBrandNextjs },
  { value: "react", label: "React", icon: IconBrandReact },
  { value: "vue", label: "Vue", icon: IconBrandVue },
  { value: "svelte", label: "Svelte", icon: IconBrandSvelte },
  { value: "angular", label: "Angular", icon: IconBrandAngular },
]

export function ComboboxWithIcons() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-icons">Framework</Label>
      <Combobox items={frameworks} autoHighlight>
        <ComboboxInput id="combobox-icons" placeholder="Select a framework" />
        <ComboboxContent>
          <ComboboxEmpty>No framework found.</ComboboxEmpty>
          <ComboboxList>
            {(item: Framework) => (
              <ComboboxItem key={item.value} value={item}>
                <item.icon />
                {item.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Gruppen und Trennlinien

Übergib Gruppen der Form { value, items } und rendere jede mit <ComboboxGroup />, <ComboboxLabel /> und <ComboboxCollection />. Leere Gruppen werden beim Filtern ausgeblendet.

"use client"

import * as React from "react"

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

type Timezone = { value: string; label: string }
type TimezoneGroup = { value: string; items: Timezone[] }

const timezones: TimezoneGroup[] = [
  {
    value: "Americas",
    items: [
      { value: "America/New_York", label: "New York (GMT-4)" },
      { value: "America/Chicago", label: "Chicago (GMT-5)" },
      { value: "America/Los_Angeles", label: "Los Angeles (GMT-7)" },
      { value: "America/Sao_Paulo", label: "São Paulo (GMT-3)" },
    ],
  },
  {
    value: "Europe",
    items: [
      { value: "Europe/London", label: "London (GMT+1)" },
      { value: "Europe/Paris", label: "Paris (GMT+2)" },
      { value: "Europe/Berlin", label: "Berlin (GMT+2)" },
    ],
  },
  {
    value: "Asia",
    items: [
      { value: "Asia/Kolkata", label: "Kolkata (GMT+5:30)" },
      { value: "Asia/Tokyo", label: "Tokyo (GMT+9)" },
      { value: "Asia/Singapore", label: "Singapore (GMT+8)" },
    ],
  },
]

export function ComboboxGroups() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-groups">Timezone</Label>
      <Combobox items={timezones} autoHighlight>
        <ComboboxInput id="combobox-groups" placeholder="Select a timezone" />
        <ComboboxContent>
          <ComboboxEmpty>No timezone found.</ComboboxEmpty>
          <ComboboxList>
            {(group: TimezoneGroup, index: number) => (
              <React.Fragment key={group.value}>
                {index > 0 ? <ComboboxSeparator /> : null}
                <ComboboxGroup items={group.items}>
                  <ComboboxLabel>{group.value}</ComboboxLabel>
                  <ComboboxCollection>
                    {(item: Timezone) => (
                      <ComboboxItem key={item.value} value={item}>
                        {item.label}
                      </ComboboxItem>
                    )}
                  </ComboboxCollection>
                </ComboboxGroup>
              </React.Fragment>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Mehrfach

Mit multiple werden Auswahlen zu Chips in <ComboboxChips />. Das Popup bleibt beim Auswählen offen, Backspace im leeren Input entfernt den letzten Chip, und die Pfeiltasten wechseln zwischen Chips.

"use client"

import type * as React from "react"
import {
  IconBrandAngular,
  IconBrandNextjs,
  IconBrandReact,
  IconBrandSvelte,
  IconBrandVue,
} from "@tabler/icons-react"

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

type Framework = {
  value: string
  label: string
  icon: React.ComponentType<{ className?: string }>
}

const frameworks: Framework[] = [
  { value: "next", label: "Next.js", icon: IconBrandNextjs },
  { value: "react", label: "React", icon: IconBrandReact },
  { value: "vue", label: "Vue", icon: IconBrandVue },
  { value: "svelte", label: "Svelte", icon: IconBrandSvelte },
  { value: "angular", label: "Angular", icon: IconBrandAngular },
]

export function ComboboxMultiple() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-multiple">Frameworks</Label>
      <Combobox
        items={frameworks}
        multiple
        autoHighlight
        defaultValue={[frameworks[0], frameworks[1]]}
      >
        <ComboboxChips>
          <ComboboxValue>
            {(values: Framework[]) => (
              <>
                {values.map((value) => (
                  <ComboboxChip key={value.value}>{value.label}</ComboboxChip>
                ))}
                <ComboboxChipsInput
                  id="combobox-multiple"
                  placeholder={values.length > 0 ? "" : "Add frameworks"}
                />
              </>
            )}
          </ComboboxValue>
        </ComboboxChips>
        <ComboboxContent>
          <ComboboxEmpty>No framework found.</ComboboxEmpty>
          <ComboboxList>
            {(item: Framework) => (
              <ComboboxItem key={item.value} value={item}>
                <item.icon />
                {item.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Verwende <ComboboxTrigger /> für ein select-ähnliches Feld. Setze das Input in <ComboboxContent />, und es wird zu einem Suchfeld mit Icon, und das Popup wird mindestens 15 rem breit.

"use client"

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

const countries = [
  { value: "ar", label: "Argentina" },
  { value: "au", label: "Australia" },
  { value: "br", label: "Brazil" },
  { value: "ca", label: "Canada" },
  { value: "de", label: "Germany" },
  { value: "fr", label: "France" },
  { value: "in", label: "India" },
  { value: "jp", label: "Japan" },
  { value: "mx", label: "Mexico" },
  { value: "nl", label: "Netherlands" },
  { value: "uk", label: "United Kingdom" },
  { value: "us", label: "United States" },
]

export function ComboboxPopupSearch() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Combobox items={countries}>
        <ComboboxTrigger aria-label="Country">
          <ComboboxValue placeholder="Select a country" />
        </ComboboxTrigger>
        <ComboboxContent>
          <ComboboxInput placeholder="Search countries" />
          <ComboboxEmpty>No country found.</ComboboxEmpty>
          <ComboboxList>
            {(item: (typeof countries)[number]) => (
              <ComboboxItem key={item.value} value={item}>
                {item.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Trigger als Button gerendert

Übergib render an den Trigger, um einen beliebigen Button zu verwenden. Das Popup verankert sich daran und behält mindestens dessen Breite.

"use client"

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

const countries = [
  { value: "ar", label: "Argentina" },
  { value: "au", label: "Australia" },
  { value: "br", label: "Brazil" },
  { value: "ca", label: "Canada" },
  { value: "de", label: "Germany" },
  { value: "fr", label: "France" },
  { value: "in", label: "India" },
  { value: "jp", label: "Japan" },
  { value: "mx", label: "Mexico" },
  { value: "nl", label: "Netherlands" },
  { value: "uk", label: "United Kingdom" },
  { value: "us", label: "United States" },
]

export function ComboboxButtonTrigger() {
  return (
    <Combobox items={countries} defaultValue={countries[6]}>
      <ComboboxTrigger
        aria-label="Country"
        render={<Button variant="outline" />}
      >
        <ComboboxValue />
      </ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput placeholder="Search countries" />
        <ComboboxEmpty>No country found.</ComboboxEmpty>
        <ComboboxList>
          {(item: (typeof countries)[number]) => (
            <ComboboxItem key={item.value} value={item}>
              {item.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Kontrolliert

Steuere die Auswahl mit value und onValueChange und das Popup mit open und onOpenChange. Das Leeren setzt den Wert auf null.

"use client"

import * as React from "react"

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

const fruits = [
  "Apple",
  "Apricot",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Grapefruit",
  "Kiwi",
  "Lychee",
  "Mango",
  "Orange",
  "Papaya",
  "Peach",
  "Pear",
  "Pineapple",
  "Plum",
  "Raspberry",
  "Strawberry",
  "Watermelon",
]

export function ComboboxControlled() {
  const [value, setValue] = React.useState<string | null>("Peach")
  const [open, setOpen] = React.useState(false)

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-controlled">Fruit</Label>
      <Combobox
        items={fruits}
        value={value}
        onValueChange={setValue}
        open={open}
        onOpenChange={setOpen}
      >
        <ComboboxInput
          id="combobox-controlled"
          placeholder="Select a fruit"
          showClear
        />
        <ComboboxContent>
          <ComboboxEmpty>No fruit found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
      <div className="flex items-center gap-2">
        <Button size="sm" variant="outline" onClick={() => setValue("Kiwi")}>
          Pick Kiwi
        </Button>
        <Button size="sm" variant="outline" onClick={() => setOpen(!open)}>
          {open ? "Close" : "Open"}
        </Button>
      </div>
      <p className="text-sm text-muted-foreground">Value: {value ?? "none"}</p>
    </div>
  )
}

Deaktivierte, ungültige und deaktivierte Einträge

disabled an der Root dimmt das Feld und seine Buttons. aria-invalid am Input zeichnet den Fehlerring. Deaktivierte Einträge werden von den Pfeiltasten übersprungen.

"use client"

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

const fruits = [
  "Apple",
  "Apricot",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Grapefruit",
  "Kiwi",
  "Lychee",
  "Mango",
  "Orange",
  "Papaya",
  "Peach",
  "Pear",
  "Pineapple",
  "Plum",
  "Raspberry",
  "Strawberry",
  "Watermelon",
]

export function ComboboxStates() {
  return (
    <div className="grid w-full max-w-xl gap-6 sm:grid-cols-2">
      <div className="flex flex-col gap-2">
        <Label htmlFor="combobox-disabled">Disabled</Label>
        <Combobox items={fruits} disabled defaultValue="Apple">
          <ComboboxInput id="combobox-disabled" showClear />
          <ComboboxContent>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="combobox-invalid">Invalid</Label>
        <Combobox items={fruits}>
          <ComboboxInput
            id="combobox-invalid"
            aria-invalid
            placeholder="Required"
          />
          <ComboboxContent>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem
                  key={item}
                  value={item}
                  disabled={item.startsWith("B")}
                >
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
        <p className="text-sm text-muted-foreground">
          Items starting with B are disabled.
        </p>
      </div>
    </div>
  )
}

Langer Inhalt und große Listen

Lange Labels und Labels ohne Umbruchstelle werden umgebrochen, statt das Popup zu verbreitern. limit begrenzt, wie viele Treffer gerendert werden, was eine Liste mit 500 Einträgen schnell hält.

"use client"

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

const longItems = [
  "A very long option label that wraps onto a second line instead of pushing the popup wider than its input",
  "supercalifragilisticexpialidocious-unbroken-string-without-any-spaces-at-all-anywhere",
  "olivia.martin+newsletter-subscriptions@a-very-long-company-domain.example.com",
  "👩‍👩‍👧‍👦 Family 🧑🏽‍💻 Developer 🏳️‍🌈",
  "東京都千代田区丸の内一丁目",
  "",
  "Short",
]

const manyItems = Array.from({ length: 500 }, (_, index) => `Item ${index + 1}`)

export function ComboboxLongContent() {
  return (
    <div className="grid w-full max-w-xl gap-6 sm:grid-cols-2">
      <div className="flex w-full max-w-60 flex-col gap-2">
        <Label htmlFor="combobox-long">Long labels</Label>
        <Combobox items={longItems} defaultValue={longItems[1]}>
          <ComboboxInput id="combobox-long" placeholder="Pick one" showClear />
          <ComboboxContent>
            <ComboboxEmpty>
              Nothing matches this unusually long query, try something else.
            </ComboboxEmpty>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item || "(empty)"}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="combobox-many">500 items</Label>
        <Combobox items={manyItems} limit={100}>
          <ComboboxInput id="combobox-many" placeholder="Search items" />
          <ComboboxContent>
            <ComboboxEmpty>No item found.</ComboboxEmpty>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
        <p className="text-sm text-muted-foreground">
          Shows the first 100 matches.
        </p>
      </div>
    </div>
  )
}

Asynchrone Suche

Schalte das integrierte Filtern mit filter={null} ab, lade Daten bei onInputValueChange und zeige den Fortschritt in <ComboboxStatus /> an, das ihn Screenreadern ansagt. Die Popup-Höhe animiert, wenn sich die Ergebnisse ändern.

"use client"

import * as React from "react"
import { IconLoader2 } from "@tabler/icons-react"

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

const countries = [
  { value: "ar", label: "Argentina" },
  { value: "au", label: "Australia" },
  { value: "br", label: "Brazil" },
  { value: "ca", label: "Canada" },
  { value: "de", label: "Germany" },
  { value: "fr", label: "France" },
  { value: "in", label: "India" },
  { value: "jp", label: "Japan" },
  { value: "mx", label: "Mexico" },
  { value: "nl", label: "Netherlands" },
  { value: "es", label: "Spain" },
  { value: "se", label: "Sweden" },
  { value: "ch", label: "Switzerland" },
  { value: "za", label: "South Africa" },
  { value: "kr", label: "South Korea" },
  { value: "uk", label: "United Kingdom" },
  { value: "us", label: "United States" },
]

export function ComboboxAsync() {
  const [query, setQuery] = React.useState("")
  const [results, setResults] = React.useState(countries.slice(0, 5))
  const [loading, setLoading] = React.useState(false)
  const runRef = React.useRef(0)

  React.useEffect(() => {
    const run = ++runRef.current
    const timer = setTimeout(() => {
      setLoading(true)
      setTimeout(() => {
        if (run !== runRef.current) {
          return
        }
        const needle = query.trim().toLowerCase()
        setResults(
          countries.filter((country) =>
            country.label.toLowerCase().includes(needle)
          )
        )
        setLoading(false)
      }, 600)
    }, 150)
    return () => {
      clearTimeout(timer)
      runRef.current += 1
    }
  }, [query])

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-async">Country</Label>
      <Combobox
        items={results}
        filter={null}
        inputValue={query}
        onInputValueChange={setQuery}
      >
        <ComboboxInput id="combobox-async" placeholder="Search countries" />
        <ComboboxContent>
          <ComboboxStatus>
            {loading ? (
              <>
                <IconLoader2 className="animate-spin" />
                Searching…
              </>
            ) : null}
          </ComboboxStatus>
          {loading ? null : (
            <ComboboxEmpty>No country matches “{query}”.</ComboboxEmpty>
          )}
          <ComboboxList>
            {(item: (typeof countries)[number]) => (
              <ComboboxItem key={item.value} value={item}>
                {item.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

In einem Sheet

Das Popup liegt über dem Sheet, und Escape schließt zuerst das Popup, dann das Sheet.

"use client"

import { Button } from "@/components/ui/button"
import {
  Combobox,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"
import {
  Sheet,
  SheetBody,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet"

type Timezone = { value: string; label: string }
type TimezoneGroup = { value: string; items: Timezone[] }

const timezones: TimezoneGroup[] = [
  {
    value: "Americas",
    items: [
      { value: "America/New_York", label: "New York (GMT-4)" },
      { value: "America/Chicago", label: "Chicago (GMT-5)" },
      { value: "America/Los_Angeles", label: "Los Angeles (GMT-7)" },
      { value: "America/Sao_Paulo", label: "São Paulo (GMT-3)" },
    ],
  },
  {
    value: "Europe",
    items: [
      { value: "Europe/London", label: "London (GMT+1)" },
      { value: "Europe/Paris", label: "Paris (GMT+2)" },
      { value: "Europe/Berlin", label: "Berlin (GMT+2)" },
    ],
  },
  {
    value: "Asia",
    items: [
      { value: "Asia/Kolkata", label: "Kolkata (GMT+5:30)" },
      { value: "Asia/Tokyo", label: "Tokyo (GMT+9)" },
      { value: "Asia/Singapore", label: "Singapore (GMT+8)" },
    ],
  },
]

export function ComboboxInSheet() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>
        Open sheet
      </SheetTrigger>
      <SheetContent>
        <SheetHeader>
          <SheetTitle>Preferences</SheetTitle>
          <SheetDescription>
            Choose the timezone for your reports.
          </SheetDescription>
        </SheetHeader>
        <SheetBody>
          <div className="flex flex-col gap-2">
            <Label htmlFor="combobox-sheet">Timezone</Label>
            <Combobox items={timezones} autoHighlight>
              <ComboboxInput
                id="combobox-sheet"
                placeholder="Select a timezone"
              />
              <ComboboxContent>
                <ComboboxEmpty>No timezone found.</ComboboxEmpty>
                <ComboboxList>
                  {(group: TimezoneGroup) => (
                    <ComboboxGroup key={group.value} items={group.items}>
                      <ComboboxLabel>{group.value}</ComboboxLabel>
                      <ComboboxCollection>
                        {(item: Timezone) => (
                          <ComboboxItem key={item.value} value={item}>
                            {item.label}
                          </ComboboxItem>
                        )}
                      </ComboboxCollection>
                    </ComboboxGroup>
                  )}
                </ComboboxList>
              </ComboboxContent>
            </Combobox>
          </div>
        </SheetBody>
      </SheetContent>
    </Sheet>
  )
}

Rechts nach links

Das Popup übernimmt die Richtung des Felds, sodass Löschen-Button, Chips und Einträge ohne zusätzliche Props gespiegelt werden.

"use client"

import { DirectionProvider } from "@base-ui/react/direction-provider"

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

const cities = ["القاهرة", "الرياض", "دبي", "بيروت", "عمّان", "الدوحة"]

export function ComboboxRtl() {
  return (
    <DirectionProvider direction="rtl">
      <div dir="rtl" className="flex w-full max-w-xs flex-col gap-4">
        <div className="flex flex-col gap-2">
          <Label htmlFor="combobox-rtl">المدينة</Label>
          <Combobox items={cities} defaultValue={cities[2]}>
            <ComboboxInput
              id="combobox-rtl"
              placeholder="اختر مدينة"
              showClear
            />
            <ComboboxContent>
              <ComboboxEmpty>لا توجد نتائج.</ComboboxEmpty>
              <ComboboxList>
                {(item: string) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxList>
            </ComboboxContent>
          </Combobox>
        </div>
        <div className="flex flex-col gap-2">
          <Label htmlFor="combobox-rtl-chips">المدن</Label>
          <Combobox items={cities} multiple defaultValue={[cities[0]]}>
            <ComboboxChips>
              <ComboboxValue>
                {(values: string[]) => (
                  <>
                    {values.map((value) => (
                      <ComboboxChip key={value}>{value}</ComboboxChip>
                    ))}
                    <ComboboxChipsInput id="combobox-rtl-chips" />
                  </>
                )}
              </ComboboxValue>
            </ComboboxChips>
            <ComboboxContent>
              <ComboboxList>
                {(item: string) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxList>
            </ComboboxContent>
          </Combobox>
        </div>
      </div>
    </DirectionProvider>
  )
}

Tastatur

Taste	Aktion
`↓↑`	Öffnet das Popup und bewegt die Hervorhebung durch die Treffer. Deaktivierte Einträge werden übersprungen.
`Enter`	Wählt den hervorgehobenen Eintrag aus. Ist nichts hervorgehoben, schließt es das Popup und lässt das Formular absenden.
`Escape`	Schließt das Popup. Ist es bereits geschlossen, werden Wert und Input geleert.
`HomeEnd`	Setzt den Textcursor an den Anfang oder das Ende des Inputs.
`Backspace`	In einem leeren Chips-Input wird der letzte Chip entfernt. Auf einem fokussierten Chip wird dieser entfernt.
`←→`	Mit Chips wechselt der Fokus zwischen Chips und zurück zum Input. In Rechts-nach-links-Layouts gespiegelt.
`Tab`	Schließt das Popup und setzt den Fokus weiter.

Barrierefreiheit

Gib dem Input über id und htmlFor ein sichtbares <label> oder ein aria-label. Ein <ComboboxTrigger /> ohne sichtbaren Text braucht ebenfalls ein aria-label.
Der Chevron-Button ist mit „Show options“ beschriftet, der Löschen-Button mit „Clear selection“ und der Entfernen-Button jedes Chips mit „Remove“.
Die Hervorhebung wandert mit aria-activedescendant, sodass der Fokus beim Durchsuchen im Input bleibt.
Inputs verwenden auf Touchscreens eine 16-px-Schrift, damit iOS nicht zoomt, und Einträge wachsen auf ein 44-px-Tippziel.

API-Referenz

Basiert auf der Base UI Combobox. Jeder Teil akzeptiert die Props der Primitive, die er umschließt; die Tabellen listen die am häufigsten genutzten auf.

Combobox

Prop	Typ	Standard
`items`Die Optionen. Werden beim Tippen gefiltert und an die Render-Funktion der Liste übergeben.	`Item[] \| Group[]`	`–`
`multiple`Mehrere Werte auswählen, als Chips angezeigt.	`boolean`	`false`
`value`	`Value \| Value[] \| null`	`–`
`defaultValue`	`Value \| Value[] \| null`	`–`
`onValueChange`	`(value, details) => void`	`–`
`open`	`boolean`	`–`
`defaultOpen`	`boolean`	`false`
`onOpenChange`	`(open: boolean, details) => void`	`–`
`inputValue`	`string`	`–`
`defaultInputValue`	`string`	`–`
`onInputValueChange`	`(inputValue: string, details) => void`	`–`
`filter`Eigenes Matching. null schaltet das Filtern für serverseitige Suche ab.	`((item, query, itemToString) => boolean) \| null`	`–`
`limit`Maximale Anzahl gerenderter Treffer. -1 bedeutet alle.	`number`	`-1`
`autoHighlight`Hebt den ersten Treffer beim Tippen hervor.	`boolean`	`false`
`highlightItemOnHover`	`boolean`	`true`
`openOnInputClick`	`boolean`	`true`
`loopFocus`Die Hervorhebung vom letzten zum ersten Eintrag umbrechen.	`boolean`	`true`
`itemToStringLabel`Text, der im Input für einen Objekt-Eintrag angezeigt wird.	`(item) => string`	`–`
`itemToStringValue`Wert, der bei einem Objekt-Eintrag mit dem Formular gesendet wird.	`(item) => string`	`–`
`isItemEqualToValue`	`(item, value) => boolean`	`–`
`name`	`string`	`–`
`required`	`boolean`	`false`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`modal`Sperrt das Scrollen der Seite und Klicks nach außen, solange geöffnet.	`boolean`	`false`
`virtualized`Setzen, wenn Einträge mit einem Virtualizer gerendert werden.	`boolean`	`false`
`locale`Locale, die für das Matching verwendet wird.	`Intl.LocalesArgument`	`–`

ComboboxInput

Außerhalb des Popups rendert es das vollständige Feld. In <ComboboxContent /> wird es zu einem kompakten Suchfeld.

Prop	Typ	Standard
`showTrigger`Zeigt den Chevron-Button. Im Popup immer aus, sofern nicht gesetzt.	`boolean`	`true outside the popup`
`showClear`Zeigt einen Löschen-Button anstelle des Chevrons, solange ein Wert vorhanden ist.	`boolean`	`false`
`className`Wird auf die Input-Gruppe um das Input angewendet.	`string`	`–`
`disabled`	`boolean`	`false`
`placeholder`	`string`	`–`

Attribut	Beschreibung
`data-slot="combobox-input-group"`	Das Feld um das Input.
`data-slot="combobox-input"`	Das Texteingabefeld.
`data-slot="combobox-input-actions"`	Hält die Buttons für Chevron und Löschen in einer gestapelten Zelle.
`data-popup-open`	Vorhanden am Input, solange das Popup geöffnet ist.
`data-popup-side`	Die Seite, auf der sich das Popup geöffnet hat.
`data-list-empty`	Vorhanden, wenn nichts passt.
`data-disabled`	Vorhanden, wenn deaktiviert.
`data-invalid`	Vorhanden, wenn ungültig innerhalb eines Base UI Field.

ComboboxTrigger

Prop	Typ	Standard
`children`Normalerweise ein <ComboboxValue />. Der Chevron wird danach hinzugefügt.	`ReactNode`	`–`
`render`Wenn gesetzt, werden die integrierten Feld-Stile übersprungen.	`ReactElement \| (props, state) => ReactElement`	`<button>`

Attribut	Beschreibung
`data-slot="combobox-trigger"`	Der Trigger-Button.
`data-slot="combobox-trigger-value"`	Umschließt den gekürzten Wert.
`data-slot="combobox-trigger-icon"`	Der Chevron. Kippt, solange geöffnet.
`data-popup-open`	Vorhanden, solange das Popup geöffnet ist.
`data-placeholder`	Vorhanden, solange kein Wert ausgewählt ist.

ComboboxValue

Prop	Typ	Standard
`children`Rendere den ausgewählten Wert selbst, zum Beispiel als Chips.	`ReactNode \| (value) => ReactNode`	`–`
`placeholder`Wird angezeigt, solange nichts ausgewählt ist.	`ReactNode`	`–`

ComboboxContent

Prop	Typ	Standard
`side`	`"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"`	`"bottom"`
`align`	`"start" \| "center" \| "end"`	`"start"`
`sideOffset`	`number`	`6`
`alignOffset`	`number`	`0`
`anchor`Positioniert sich an einem anderen Element. Standardmäßig das Feld. Siehe useComboboxAnchor.	`Element \| RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	`–`
`dir`Standardmäßig die Richtung des Felds.	`"ltr" \| "rtl"`	`–`

Attribut	Beschreibung
`data-slot="combobox-positioner"`	Positioniert das Popup.
`data-slot="combobox-content"`	Die Popup-Fläche.
`data-slot="combobox-content-sizer"`	Wird gemessen, um die Höhe des Popups zu animieren, wenn sich die Treffer ändern.
`data-open`	Vorhanden, solange geöffnet.
`data-side`	Die Seite, auf der es sich geöffnet hat.
`data-align`	Seine Ausrichtung.
`data-empty`	Vorhanden, wenn nichts passt.
`data-starting-style`	Vorhanden während der Einblendanimation.
`data-ending-style`	Vorhanden während der Ausblendanimation.
`--combobox-item-radius`	Radius des Eintrags, abgeleitet vom Popup-Radius abzüglich seines Paddings.

ComboboxList

Prop	Typ	Standard
`children`Wird für jeden Treffer in items aufgerufen.	`ReactNode \| (item, index) => ReactNode`	`–`

Attribut	Beschreibung
`data-slot="combobox-list"`	Die scrollende Liste.

ComboboxItem

Prop	Typ	Standard
`value`Der Eintrag, den diese Zeile darstellt.	`Item`	`–`
`disabled`	`boolean`	`false`
`render`	`ReactElement \| (props, state) => ReactElement`	`<div>`

Attribut	Beschreibung
`data-slot="combobox-item"`	Eine Option.
`data-slot="combobox-item-indicator"`	Der Haken, der bei Auswahl hereinskaliert.
`data-highlighted`	Vorhanden, solange hervorgehoben.
`data-selected`	Vorhanden, wenn ausgewählt.
`data-disabled`	Vorhanden, wenn deaktiviert.

ComboboxGroup, ComboboxLabel und ComboboxCollection

Prop	Typ	Standard
`items`Auf ComboboxGroup: die eigenen Einträge der Gruppe.	`Item[]`	`–`
`children`Auf ComboboxCollection: rendert jeden Treffer.	`(item, index) => ReactNode`	`–`

Attribut	Beschreibung
`data-slot="combobox-group"`	Eine Gruppe von Einträgen.
`data-slot="combobox-label"`	Die Gruppenüberschrift.

ComboboxEmpty, ComboboxStatus und ComboboxSeparator

<ComboboxEmpty /> zeigt seine Kinder nur, wenn nichts passt. <ComboboxStatus /> ist eine Live-Region für Lade- und Ergebnismeldungen. Beide fallen im leeren Zustand zu nichts zusammen.

Attribut	Beschreibung
`data-slot="combobox-empty"`	Die Meldung „keine Ergebnisse“.
`data-slot="combobox-status"`	Die Live-Statusmeldung.
`data-slot="combobox-separator"`	Eine Trennlinie zwischen Gruppen.

ComboboxClear

Prop	Typ	Standard
`children`	`ReactNode`	`<IconX />`

Attribut	Beschreibung
`data-slot="combobox-clear"`	Beschriftet mit „Clear selection“.
`data-visible`	Vorhanden, solange es etwas zu leeren gibt.

ComboboxChips

Prop	Typ	Standard
`className`Wird auf das Feld angewendet, das die Chips umschließt.	`string`	`–`

Attribut	Beschreibung
`data-slot="combobox-chips"`	Das Feld, das Chips und Input enthält.

ComboboxChip

Prop	Typ	Standard
`showRemove`Zeigt den Entfernen-Button.	`boolean`	`true`

Attribut	Beschreibung
`data-slot="combobox-chip"`	Ein ausgewählter Wert.
`data-slot="combobox-chip-label"`	Sein gekürztes Label.
`data-slot="combobox-chip-remove"`	Beschriftet mit „Remove“.

ComboboxChipsInput

Das Texteingabefeld nach den Chips. Akzeptiert dieselben Props wie das Base UI Input.

Attribut	Beschreibung
`data-slot="combobox-chips-input"`	Das Chips-Input.

Hooks und Helfer

useComboboxAnchor() gibt eine Ref zurück, die du an ein Element und an anchor des Contents übergibst.
useComboboxFilter() gibt locale-abhängige Matcher contains, startsWith und endsWith für filter zurück.
useComboboxFilteredItems() liest die aktuellen Treffer, für Zähler oder virtualisierte Listen.
createComboboxItems(data, { getValue }) baut eine Eintragssammlung, deren Auswahlwert eine primitive ID ist, etwa ein Datenbankschlüssel, statt des ganzen Objekts.
comboboxFieldVariants stellt die Feld-Stile bereit, um eigene Felder zu bauen.