Combobox

Um select filtrável com chips, grupos e resultados assíncronos, em um popup que se redimensiona conforme você digita.

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

Instalação

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

Adiciona o componente, os tokens de tema do HextaUI e quaisquer componentes do HextaUI dos quais ele depende.

Adicione os tokens de tema ao seu CSS global, se ainda não o fez.

Instale as dependências.

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

3
Copie e cole o código a seguir no seu projeto.
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,
Atualize os caminhos de importação para corresponder à configuração do seu projeto.

Uso

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>

Passe as opções para items e renderize cada uma com uma função dentro de <ComboboxList />. O combobox as filtra conforme você digita e renderiza apenas as correspondências. Objetos também funcionam: o label deles é exibido no input e o value é enviado.

Composição

Input

Digite no campo para filtrar a lista.

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

Gatilho de botão

Um botão mostra o valor e o campo de busca vai para dentro do popup.

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

Chips

Com multiple, cada item selecionado vira um chip antes do input.

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

Exemplos

Botão de limpar

showClear adiciona um botão de limpar que ocupa o lugar do chevron enquanto há um valor, então o campo nunca cresce.

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

Com ícones

Os ícones dentro de um item são dimensionados e atenuados para você. autoHighlight destaca a primeira correspondência durante a digitação, então Enter a seleciona.

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

Grupos e separadores

Passe grupos no formato { value, items } e renderize cada um com <ComboboxGroup />, <ComboboxLabel /> e <ComboboxCollection />. Grupos vazios ficam ocultos durante a filtragem.

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

Múltiplo

Com multiple, as seleções viram chips dentro de <ComboboxChips />. O popup permanece aberto enquanto você escolhe, Backspace no input vazio remove o último chip e as teclas de seta alternam entre os 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>
  )
}

Use <ComboboxTrigger /> para um campo no estilo select. Coloque o input dentro de <ComboboxContent /> e ele vira uma caixa de busca com ícone, e o popup se alarga para pelo menos 15rem.

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

Gatilho renderizado como um Button

Passe render ao gatilho para usar qualquer botão. O popup se ancora nele e mantém ao menos a sua largura.

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

Controlado

Controle a seleção com value e onValueChange, e o popup com open e onOpenChange. Limpar define o valor como 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>
  )
}

Itens desativados, inválidos e desativados individualmente

disabled na raiz esmaece o campo e seus botões. aria-invalid no input desenha o anel de erro. Itens desativados são ignorados pelas teclas de seta.

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

Conteúdo longo e listas grandes

Rótulos longos e sem quebra são quebrados em vez de alargar o popup. limit limita quantas correspondências são renderizadas, o que mantém rápida uma lista de 500 itens.

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

Busca assíncrona

Desative a filtragem integrada com filter={null}, busque dados em onInputValueChange e mostre o progresso em <ComboboxStatus />, que o anuncia aos leitores de tela. A altura do popup é animada conforme os resultados mudam.

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

Dentro de uma sheet

O popup fica acima do sheet, e Escape fecha o popup antes do 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>
  )
}

Da direita para a esquerda

O popup adota a direção do campo, então o botão de limpar, os chips e os itens são espelhados sem props extras.

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

Teclado

Tecla	Ação
`↓↑`	Abre o popup e move o destaque pelas correspondências. Itens desativados são ignorados.
`Enter`	Seleciona o item destacado. Sem nenhum destacado, fecha o popup e deixa o formulário ser enviado.
`Escape`	Fecha o popup. Quando já está fechado, limpa o valor e o input.
`HomeEnd`	Move o cursor de texto para o início ou o fim do input.
`Backspace`	Em um input de chips vazio, remove o último chip. Em um chip em foco, remove-o.
`←→`	Com chips, move o foco entre os chips e de volta ao input. Espelhado em layouts da direita para a esquerda.
`Tab`	Fecha o popup e move o foco adiante.

Acessibilidade

Dê ao input um <label> visível por meio de id e htmlFor, ou um aria-label. Um <ComboboxTrigger /> sem texto visível também precisa de um aria-label.
O botão de chevron tem o rótulo “Show options”, o botão de limpar “Clear selection” e o botão de remover de cada chip “Remove”.
O destaque se move com aria-activedescendant, então o foco permanece no input enquanto você navega.
Os inputs usam fonte de 16px em telas sensíveis ao toque para que o iOS não aplique zoom, e os itens crescem para uma área de toque de 44px.

Referência da API

Construído sobre o combobox do Base UI. Cada parte aceita as props da primitiva que envolve; as tabelas listam as que você mais usará.

Combobox

Prop	Tipo	Padrão
`items`As opções. Filtradas conforme você digita e passadas à render function da lista.	`Item[] \| Group[]`	`–`
`multiple`Selecione vários valores, exibidos como 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`Correspondência personalizada. null desativa a filtragem para busca no servidor.	`((item, query, itemToString) => boolean) \| null`	`–`
`limit`Número máximo de correspondências a renderizar. -1 significa todas.	`number`	`-1`
`autoHighlight`Destaca a primeira correspondência durante a digitação.	`boolean`	`false`
`highlightItemOnHover`	`boolean`	`true`
`openOnInputClick`	`boolean`	`true`
`loopFocus`Volta do último item para o primeiro ao mover o destaque.	`boolean`	`true`
`itemToStringLabel`Texto exibido no input para um item do tipo objeto.	`(item) => string`	`–`
`itemToStringValue`Valor enviado com o formulário para um item do tipo objeto.	`(item) => string`	`–`
`isItemEqualToValue`	`(item, value) => boolean`	`–`
`name`	`string`	`–`
`required`	`boolean`	`false`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`modal`Bloqueia a rolagem da página e os cliques externos enquanto aberto.	`boolean`	`false`
`virtualized`Defina ao renderizar itens com um virtualizador.	`boolean`	`false`
`locale`Locale usado na correspondência.	`Intl.LocalesArgument`	`–`

ComboboxInput

Fora do popup, renderiza o campo completo. Dentro de <ComboboxContent />, vira uma caixa de busca compacta.

Prop	Tipo	Padrão
`showTrigger`Mostra o botão de chevron. Sempre desativado dentro do popup, a menos que definido.	`boolean`	`true outside the popup`
`showClear`Mostra um botão de limpar no lugar do chevron enquanto há um valor.	`boolean`	`false`
`className`Aplicado ao input group em volta do input.	`string`	`–`
`disabled`	`boolean`	`false`
`placeholder`	`string`	`–`

Atributo	Descrição
`data-slot="combobox-input-group"`	O campo em volta do input.
`data-slot="combobox-input"`	O input de texto.
`data-slot="combobox-input-actions"`	Contém os botões de chevron e de limpar em uma única célula empilhada.
`data-popup-open`	Presente no input enquanto o popup está aberto.
`data-popup-side`	O lado em que o popup abriu.
`data-list-empty`	Presente quando nada corresponde.
`data-disabled`	Presente quando desabilitado.
`data-invalid`	Presente quando inválido dentro de um Field do Base UI.

ComboboxTrigger

Prop	Tipo	Padrão
`children`Geralmente um <ComboboxValue />. O chevron é adicionado depois dele.	`ReactNode`	`–`
`render`Quando definido, os estilos de campo integrados são ignorados.	`ReactElement \| (props, state) => ReactElement`	`<button>`

Atributo	Descrição
`data-slot="combobox-trigger"`	O botão gatilho.
`data-slot="combobox-trigger-value"`	Envolve o valor truncado.
`data-slot="combobox-trigger-icon"`	O chevron. Inverte-se enquanto aberto.
`data-popup-open`	Presente enquanto o popup está aberto.
`data-placeholder`	Presente enquanto nenhum valor está selecionado.

ComboboxValue

Prop	Tipo	Padrão
`children`Renderize o valor selecionado você mesmo, por exemplo como chips.	`ReactNode \| (value) => ReactNode`	`–`
`placeholder`Exibido enquanto nada está selecionado.	`ReactNode`	`–`

ComboboxContent

Prop	Tipo	Padrão
`side`	`"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"`	`"bottom"`
`align`	`"start" \| "center" \| "end"`	`"start"`
`sideOffset`	`number`	`6`
`alignOffset`	`number`	`0`
`anchor`Posiciona em relação a outro elemento. O padrão é o campo. Veja useComboboxAnchor.	`Element \| RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	`–`
`dir`O padrão é a direção do campo.	`"ltr" \| "rtl"`	`–`

Atributo	Descrição
`data-slot="combobox-positioner"`	Posiciona o popup.
`data-slot="combobox-content"`	A superfície do popup.
`data-slot="combobox-content-sizer"`	Medido para animar a altura do popup conforme as correspondências mudam.
`data-open`	Presente enquanto aberto.
`data-side`	O lado em que abriu.
`data-align`	Seu alinhamento.
`data-empty`	Presente quando nada corresponde.
`data-starting-style`	Presente durante a animação de entrada.
`data-ending-style`	Presente durante a animação de saída.
`--combobox-item-radius`	Raio do item, derivado do raio do popup menos o seu padding.

ComboboxList

Prop	Tipo	Padrão
`children`Chamado para cada correspondência de items.	`ReactNode \| (item, index) => ReactNode`	`–`

Atributo	Descrição
`data-slot="combobox-list"`	A lista rolável.

ComboboxItem

Prop	Tipo	Padrão
`value`O item que esta linha representa.	`Item`	`–`
`disabled`	`boolean`	`false`
`render`	`ReactElement \| (props, state) => ReactElement`	`<div>`

Atributo	Descrição
`data-slot="combobox-item"`	Uma opção.
`data-slot="combobox-item-indicator"`	A marca, que cresce ao ser selecionado.
`data-highlighted`	Presente enquanto destacado.
`data-selected`	Presente quando selecionado.
`data-disabled`	Presente quando desabilitado.

ComboboxGroup, ComboboxLabel e ComboboxCollection

Prop	Tipo	Padrão
`items`Em ComboboxGroup: os próprios itens do grupo.	`Item[]`	`–`
`children`Em ComboboxCollection: renderiza cada correspondência.	`(item, index) => ReactNode`	`–`

Atributo	Descrição
`data-slot="combobox-group"`	Um grupo de itens.
`data-slot="combobox-label"`	O título do grupo.

ComboboxEmpty, ComboboxStatus e ComboboxSeparator

<ComboboxEmpty /> exibe seus filhos apenas quando nada corresponde. <ComboboxStatus /> é uma região live para mensagens de carregamento e de resultado. Ambos colapsam a nada quando vazios.

Atributo	Descrição
`data-slot="combobox-empty"`	A mensagem de sem resultados.
`data-slot="combobox-status"`	A mensagem de status live.
`data-slot="combobox-separator"`	Um divisor entre grupos.

ComboboxClear

Prop	Tipo	Padrão
`children`	`ReactNode`	`<IconX />`

Atributo	Descrição
`data-slot="combobox-clear"`	Rotulado como “Clear selection”.
`data-visible`	Presente enquanto há algo para limpar.

ComboboxChips

Prop	Tipo	Padrão
`className`Aplicado ao campo que envolve os chips.	`string`	`–`

Atributo	Descrição
`data-slot="combobox-chips"`	O campo que contém os chips e o input.

ComboboxChip

Prop	Tipo	Padrão
`showRemove`Mostra o botão de remover.	`boolean`	`true`

Atributo	Descrição
`data-slot="combobox-chip"`	Um valor selecionado.
`data-slot="combobox-chip-label"`	Seu rótulo truncado.
`data-slot="combobox-chip-remove"`	Rotulado como “Remove”.

ComboboxChipsInput

O input de texto que fica depois dos chips. Aceita as mesmas props do input do Base UI.

Atributo	Descrição
`data-slot="combobox-chips-input"`	O input de chips.

Hooks e utilitários

useComboboxAnchor() retorna uma ref para passar a um elemento e a anchor no conteúdo.
useComboboxFilter() retorna os comparadores contains, startsWith e endsWith, sensíveis ao locale, para filter.
useComboboxFilteredItems() lê as correspondências atuais, para contagens ou listas virtualizadas.
createComboboxItems(data, { getValue }) cria uma coleção de itens cujo valor de seleção é um id primitivo, como uma chave de banco de dados, em vez do objeto inteiro.
comboboxFieldVariants expõe os estilos do campo para criar campos personalizados.