Combobox

Un select filtrable avec chips, groupes et résultats asynchrones, dans un popup qui se redimensionne pendant la saisie.

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

Ajoute le composant, les tokens de thème HextaUI et les composants HextaUI dont il dépend.

Ajoutez les tokens de thème à votre CSS global, si ce n’est pas déjà fait.

Installez les dépendances.

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

3
Copiez et collez le code suivant dans votre projet.
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,
Mettez à jour les chemins d’import selon la configuration de votre projet.

Utilisation

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>

Passez les options à items et rendez chacune avec une fonction dans <ComboboxList />. Le combobox les filtre pendant la saisie et ne rend que les correspondances. Les objets fonctionnent aussi : leur label s’affiche dans le champ et leur value est soumise.

Composition

Input

Saisissez dans le champ pour filtrer la liste.

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

Déclencheur en bouton

Un bouton affiche la valeur et le champ de recherche passe dans la popup.

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

Chips

Avec multiple, chaque élément sélectionné devient une chip avant le champ.

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

Exemples

Bouton d’effacement

showClear ajoute un bouton d’effacement qui prend la place du chevron tant qu’il y a une valeur : le champ ne grandit donc jamais.

"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>
  )
}

Avec des icônes

Les icônes dans un élément sont dimensionnées et atténuées pour vous. autoHighlight met en évidence la première correspondance pendant la saisie, de sorte que Enter la sélectionne.

"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>
  )
}

Groupes et séparateurs

Passez des groupes de la forme { value, items } et rendez chacun avec <ComboboxGroup />, <ComboboxLabel /> et <ComboboxCollection />. Les groupes vides sont masqués pendant le filtrage.

"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>
  )
}

Multiple

Avec multiple, les sélections deviennent des chips dans <ComboboxChips />. La popup reste ouverte pendant le choix, Backspace dans le champ vide supprime la dernière chip, et les flèches permettent de passer d’une chip à l’autre.

"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>
  )
}

Utilisez <ComboboxTrigger /> pour un champ de type select. Placez le champ dans <ComboboxContent /> et il devient une zone de recherche avec une icône, et la popup s’élargit à au moins 15 rem.

"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>
  )
}

Déclencheur rendu comme un Button

Passez render au déclencheur pour utiliser n’importe quel bouton. La popup s’y ancre et garde au moins sa largeur.

"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>
  )
}

Contrôlé

Contrôlez la sélection avec value et onValueChange, et la popup avec open et onOpenChange. L’effacement définit la valeur à 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>
  )
}

Éléments désactivés, invalides et désactivés individuellement

disabled sur la racine atténue le champ et ses boutons. aria-invalid sur le champ dessine l’anneau d’erreur. Les éléments désactivés sont ignorés par les flèches.

"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>
  )
}

Contenu long et grandes listes

Les libellés longs et sans coupure passent à la ligne au lieu d’élargir la popup. limit plafonne le nombre de correspondances rendues, ce qui garde rapide une liste de 500 éléments.

"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>
  )
}

Recherche asynchrone

Désactivez le filtrage intégré avec filter={null}, récupérez les données dans onInputValueChange et affichez la progression dans <ComboboxStatus />, qui l’annonce aux lecteurs d’écran. La hauteur de la popup s’anime à mesure que les résultats changent.

"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>
  )
}

Dans une sheet

La popup se superpose à la sheet, et Escape ferme la popup avant la 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>
  )
}

De droite à gauche

La popup reprend la direction du champ : le bouton d’effacement, les chips et les éléments s’inversent donc sans props supplémentaires.

"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>
  )
}

Clavier

Touche	Action
`↓↑`	Ouvre la popup et déplace la mise en évidence parmi les correspondances. Les éléments désactivés sont ignorés.
`Enter`	Sélectionne l’élément mis en évidence. Sans mise en évidence, ferme la popup et laisse le formulaire se soumettre.
`Escape`	Ferme la popup. Si elle est déjà fermée, efface la valeur et le champ.
`HomeEnd`	Déplace le curseur de texte au début ou à la fin du champ.
`Backspace`	Dans un champ de chips vide, supprime la dernière chip. Sur une chip ayant le focus, la supprime.
`←→`	Avec des chips, déplace le focus entre les chips et revient au champ. Inversé dans les mises en page de droite à gauche.
`Tab`	Ferme la popup et déplace le focus plus loin.

Accessibilité

Donnez au champ un <label> visible via id et htmlFor, ou un aria-label. Un <ComboboxTrigger /> sans texte visible a aussi besoin d’un aria-label.
Le bouton du chevron est étiqueté « Show options », le bouton d’effacement « Clear selection » et le bouton de suppression de chaque chip « Remove ».
La mise en évidence se déplace avec aria-activedescendant, si bien que le focus reste dans le champ pendant la navigation.
Les champs utilisent une police de 16 px sur écran tactile pour qu’iOS ne zoome pas, et les éléments passent à une cible tactile de 44 px.

Référence de l’API

Construit sur le combobox de Base UI. Chaque partie accepte les props de la primitive qu’elle enveloppe ; les tableaux listent celles que vous utiliserez le plus.

Combobox

Prop	Type	Par défaut
`items`Les options. Filtrées pendant la saisie et transmises à la fonction de rendu de la liste.	`Item[] \| Group[]`	`–`
`multiple`Sélectionne plusieurs valeurs, affichées sous forme de chips.	`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`Correspondance personnalisée. null désactive le filtrage pour une recherche côté serveur.	`((item, query, itemToString) => boolean) \| null`	`–`
`limit`Nombre maximal de correspondances à rendre. -1 signifie toutes.	`number`	`-1`
`autoHighlight`Met en évidence la première correspondance pendant la saisie.	`boolean`	`false`
`highlightItemOnHover`	`boolean`	`true`
`openOnInputClick`	`boolean`	`true`
`loopFocus`Reboucle la mise en évidence du dernier élément au premier.	`boolean`	`true`
`itemToStringLabel`Texte affiché dans le champ pour un élément objet.	`(item) => string`	`–`
`itemToStringValue`Valeur soumise avec le formulaire pour un élément objet.	`(item) => string`	`–`
`isItemEqualToValue`	`(item, value) => boolean`	`–`
`name`	`string`	`–`
`required`	`boolean`	`false`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`modal`Verrouille le défilement de la page et les clics extérieurs pendant l’ouverture.	`boolean`	`false`
`virtualized`À définir lors du rendu des éléments avec un virtualiseur.	`boolean`	`false`
`locale`Locale utilisée pour la correspondance.	`Intl.LocalesArgument`	`–`

ComboboxInput

En dehors de la popup, il rend le champ complet. Dans <ComboboxContent />, il devient une zone de recherche compacte.

Prop	Type	Par défaut
`showTrigger`Affiche le bouton du chevron. Toujours désactivé dans la popup sauf si défini.	`boolean`	`true outside the popup`
`showClear`Affiche un bouton d’effacement à la place du chevron tant qu’il y a une valeur.	`boolean`	`false`
`className`Appliqué au groupe de champ autour du champ.	`string`	`–`
`disabled`	`boolean`	`false`
`placeholder`	`string`	`–`

Attribut	Description
`data-slot="combobox-input-group"`	Le champ autour de l’entrée.
`data-slot="combobox-input"`	Le champ de texte.
`data-slot="combobox-input-actions"`	Contient les boutons du chevron et d’effacement dans une seule cellule superposée.
`data-popup-open`	Présent sur le champ tant que la popup est ouverte.
`data-popup-side`	Le côté sur lequel la popup s’est ouverte.
`data-list-empty`	Présent lorsque rien ne correspond.
`data-disabled`	Présent lorsque l’élément est désactivé.
`data-invalid`	Présent lorsqu’elle est invalide dans un Field de Base UI.

ComboboxTrigger

Prop	Type	Par défaut
`children`En général un <ComboboxValue />. Le chevron est ajouté après.	`ReactNode`	`–`
`render`Lorsqu’il est défini, les styles de champ intégrés sont ignorés.	`ReactElement \| (props, state) => ReactElement`	`<button>`

Attribut	Description
`data-slot="combobox-trigger"`	Le bouton déclencheur.
`data-slot="combobox-trigger-value"`	Enveloppe la valeur tronquée.
`data-slot="combobox-trigger-icon"`	Le chevron. Se retourne à l’ouverture.
`data-popup-open`	Présent tant que la popup est ouverte.
`data-placeholder`	Présent tant qu’aucune valeur n’est sélectionnée.

ComboboxValue

Prop	Type	Par défaut
`children`Rendez vous-même la valeur sélectionnée, par exemple sous forme de chips.	`ReactNode \| (value) => ReactNode`	`–`
`placeholder`Affiché tant que rien n’est sélectionné.	`ReactNode`	`–`

ComboboxContent

Prop	Type	Par défaut
`side`	`"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"`	`"bottom"`
`align`	`"start" \| "center" \| "end"`	`"start"`
`sideOffset`	`number`	`6`
`alignOffset`	`number`	`0`
`anchor`Se positionne par rapport à un autre élément. Par défaut, le champ. Voir useComboboxAnchor.	`Element \| RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	`–`
`dir`Par défaut, la direction du champ.	`"ltr" \| "rtl"`	`–`

Attribut	Description
`data-slot="combobox-positioner"`	Positionne la popup.
`data-slot="combobox-content"`	La surface de la popup.
`data-slot="combobox-content-sizer"`	Mesuré pour animer la hauteur de la popup lorsque les correspondances changent.
`data-open`	Présent tant que l’élément est ouvert.
`data-side`	Le côté sur lequel elle s’est ouverte.
`data-align`	Son alignement.
`data-empty`	Présent lorsque rien ne correspond.
`data-starting-style`	Présent pendant l’animation d’entrée.
`data-ending-style`	Présent pendant l’animation de sortie.
`--combobox-item-radius`	Rayon de l’élément, déduit du rayon de la popup moins son remplissage.

ComboboxList

Prop	Type	Par défaut
`children`Appelé pour chaque correspondance de items.	`ReactNode \| (item, index) => ReactNode`	`–`

Attribut	Description
`data-slot="combobox-list"`	La liste défilante.

ComboboxItem

Prop	Type	Par défaut
`value`L’élément que cette ligne représente.	`Item`	`–`
`disabled`	`boolean`	`false`
`render`	`ReactElement \| (props, state) => ReactElement`	`<div>`

Attribut	Description
`data-slot="combobox-item"`	Une option.
`data-slot="combobox-item-indicator"`	La coche, qui apparaît en zoom à la sélection.
`data-highlighted`	Présent pendant la mise en surbrillance.
`data-selected`	Présent lorsqu’il est sélectionné.
`data-disabled`	Présent lorsque l’élément est désactivé.

ComboboxGroup, ComboboxLabel et ComboboxCollection

Prop	Type	Par défaut
`items`Sur ComboboxGroup : les éléments propres au groupe.	`Item[]`	`–`
`children`Sur ComboboxCollection : rend chaque correspondance.	`(item, index) => ReactNode`	`–`

Attribut	Description
`data-slot="combobox-group"`	Un groupe d’éléments.
`data-slot="combobox-label"`	Le titre du groupe.

ComboboxEmpty, ComboboxStatus et ComboboxSeparator

<ComboboxEmpty /> n’affiche ses enfants que lorsque rien ne correspond. <ComboboxStatus /> est une région live pour les messages de chargement et de résultat. Les deux se réduisent à rien lorsqu’ils sont vides.

Attribut	Description
`data-slot="combobox-empty"`	Le message d’absence de résultats.
`data-slot="combobox-status"`	Le message d’état live.
`data-slot="combobox-separator"`	Un séparateur entre les groupes.

ComboboxClear

Prop	Type	Par défaut
`children`	`ReactNode`	`<IconX />`

Attribut	Description
`data-slot="combobox-clear"`	Étiqueté « Clear selection ».
`data-visible`	Présent tant qu’il y a quelque chose à effacer.

ComboboxChips

Prop	Type	Par défaut
`className`Appliqué au champ qui enveloppe les chips.	`string`	`–`

Attribut	Description
`data-slot="combobox-chips"`	Le champ qui contient les chips et la saisie.

ComboboxChip

Prop	Type	Par défaut
`showRemove`Affiche le bouton de suppression.	`boolean`	`true`

Attribut	Description
`data-slot="combobox-chip"`	Une valeur sélectionnée.
`data-slot="combobox-chip-label"`	Son libellé tronqué.
`data-slot="combobox-chip-remove"`	Étiqueté « Remove ».

ComboboxChipsInput

Le champ de texte placé après les chips. Accepte les mêmes props que l’input de Base UI.

Attribut	Description
`data-slot="combobox-chips-input"`	Le champ des chips.

Hooks et utilitaires

useComboboxAnchor() retourne une ref à passer à un élément et à anchor sur le contenu.
useComboboxFilter() retourne des comparateurs contains, startsWith et endsWith sensibles à la locale pour filter.
useComboboxFilteredItems() lit les correspondances actuelles, pour les compteurs ou les listes virtualisées.
createComboboxItems(data, { getValue }) construit une collection d’éléments dont la valeur de sélection est un id primitif, comme une clé de base de données, plutôt que l’objet entier.
comboboxFieldVariants expose les styles de champ pour construire des champs personnalisés.