Combobox

Componentes/Entrada e seleção

ImplementaçãoHTML/CSS/JSArk/ZagReact · shadcn/Base UIAngular

Recipe React distribuída como source, com comportamento Base UI e classes/tokens públicos do Combobox TIS.

DesignUsoImplementaçãoAcessibilidade

Seção da documentaçãoDesignUsoImplementaçãoAcessibilidade

Design

Preview funcional

Executado pela recipe React distribuída via shadcn e baseada em Base UI.

Carregando preview funcional…

Abrir playground React · shadcn/Base UI

Anatomia

Country * 6

1 2 3

• Brazil

4 5

Type to filter countries.

1 Field (.ds-combobox) — wrapper com input, ícone, clear e chevron.
2 Input (.ds-combobox__input) — texto editável com role="combobox".
3 Ícone (.ds-combobox__icon) — opcional, decorativo.
4 Listbox (.ds-combobox__listbox) — popup com opções filtráveis.
5 Option (.ds-combobox__option) — item selecionável com role="option".
6 Label e helper — externos via ds-field (ADR-017).

Padrão

Country*

Type to filter countries.

Listbox aberto

Componha com ds-field para label, helper e erro. Envolva .ds-combobox e .ds-combobox__listbox em .ds-combobox-anchor para posicionar o popup. O módulo público ds-tis/combobox (initComboboxes / destroyComboboxes) é obrigatório para abertura, filtro, seleção e teclado. Evento: ds-combobox-change.

Country*

• Argentina
• Brazil
• Chile
• Colombia (unavailable)

Type to filter countries.

Tamanhos

Size	Height	Padding
Small (--sm)	component.combobox.height.sm (32px)	component.combobox.padding-x.sm
Medium (--md)	component.combobox.height.md (40px)	component.combobox.padding-x.md
Large (--lg)	component.combobox.height.lg (48px)	component.combobox.padding-x.lg

Estados

Error

Country*

Please select a country.

Disabled

Read-only

API no Figma

O component set vivo compõe field compartilhado (ADR-019) com listbox local. State cobre Default, Hover, Focus e Disabled; Filled, Error e Read-only são propriedades separadas, como em Select.

Propriedade	Tipo	Equivalente no repo
Show Label	BOOLEAN	ds-field + .ds-field__label
Label	TEXT	.ds-field__label
Placeholder	TEXT	placeholder no input
Content	TEXT	valor preenchido em .ds-combobox__input
Show Left Icon / Left Icon	BOOLEAN / INSTANCE_SWAP	.ds-combobox__icon
Show Clear Button / Clear Icon	BOOLEAN / INSTANCE_SWAP	.ds-combobox__clear
Chevron Icon	INSTANCE_SWAP	.ds-combobox__chevron
Show Helper Text / Helper Text	BOOLEAN / TEXT	.ds-field__helper
Error Message	TEXT	.ds-field__error + ds-combobox--error
Size	VARIANT	ds-combobox--sm / --md / --lg
State	VARIANT	Default, Hover, Focus, Disabled
Filled / Error / Read-only	BOOLEAN	ds-combobox--filled, --error, --readonly

Uso

Quando usar

Use Combobox quando

O usuário precisa digitar para filtrar opções, escolher de listas longas ou editar o valor antes de confirmar a seleção.

Não use Combobox quando

Menos de 5 opções fixas — prefira Radio. Lista fechada sem busca — use Select. Menu de ações — use Menu.

Boas práticas

Faça

Permita busca por digitação e destaque a opção selecionada com aria-selected="true".

Não faça

Não use combobox para escolhas booleanas — use Toggle ou Radio.

Diretrizes de conteúdo

Regra	Exemplo
Placeholder em sentence case	"Choose a country" — not "COUNTRY"
Options concisas e consistentes	"Brazil", "United States"
Sempre com ds-field + label	<label for="country">Country</label>

Relacionados

Select Input Menu Form Field

Composição React

import {
  Combobox,
  ComboboxAnchor,
  ComboboxChevron,
  ComboboxClear,
  ComboboxContent,
  ComboboxControl,
  ComboboxField,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
  ComboboxPortal,
  ComboboxPositioner,
} from "@/components/ui/combobox"

<Combobox items={countries} itemToStringLabel={(item) => item.label}>
  <ComboboxField>
    <ComboboxLabel htmlFor="country">País</ComboboxLabel>
    <ComboboxAnchor>
      <ComboboxControl>
        <ComboboxInput id="country" placeholder="Busque um país" />
        <ComboboxClear />
        <ComboboxChevron />
      </ComboboxControl>
      <ComboboxPortal>
        <ComboboxPositioner>
          <ComboboxContent>
            <ComboboxList>
              {(item, index) => (
                <ComboboxItem key={item.value} index={index} value={item}>
                  {item.label}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </ComboboxPositioner>
      </ComboboxPortal>
    </ComboboxAnchor>
  </ComboboxField>
</Combobox>

Implementação

Status

Beta

Distribuição

Source via shadcn

Instalação

Configure o namespace uma única vez na integração React.

npm

npx shadcn@latest add @tis/combobox

pnpm

pnpm dlx shadcn@latest add @tis/combobox

yarn

yarn dlx shadcn@latest add @tis/combobox

bun

bunx --bun shadcn@latest add @tis/combobox

Contrato público

Item do registry

@tis/combobox

Provider

Base UI

Distribuição

Source copiado para a aplicação

Status

Beta

Arquitetura técnica

Abrir JSON do registry

Inspecionar source distribuído

Acessibilidade

Interação por teclado

Tecla	Ação
Arrow Down / Arrow Up	Move o foco entre opções no listbox aberto
Enter	Seleciona a opção focada e fecha o listbox
Escape	Fecha o listbox e retorna foco ao input
Typing	Filtra opções (implementação do produto)

Accessibility

Critério WCAG	Requisito	Status
4.1.2 Name, Role, Value (A)	role="combobox", aria-expanded, aria-controls, role="listbox" / role="option"	✓
1.3.1 Info and Relationships (A)	Label via ds-field; erro com aria-invalid + aria-describedby	✓
2.4.11 Focus Appearance (AA)	Focus ring visível no field e nas opções	✓

Responsabilidade da saída

Preserve a semântica da Base UI e teste conteúdo real, foco visível e nomes acessíveis na aplicação consumidora.

Evidência de validação

Coberta pelo Storybook da saída independente e por verificações de browser, responsividade, teclado, Axe e bundle.

Abrir referência estável