Combobox

Componentes/Entrada e seleção

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

Filtra e seleciona uma opção em conjuntos extensos, preservando valor de formulário e navegação por teclado.

DesignUsoImplementaçãoAcessibilidade

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

Design

Preview funcional

Executado pelo runtime JavaScript estável ds-tis/combobox.

Carregando preview funcional…

Abrir playground HTML/CSS/JS

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

Implementação

Status

Estável

Distribuição

Pacote npm

Instalação

npm

npm install ds-tis

pnpm

pnpm add ds-tis

yarn

yarn add ds-tis

bun

bun add ds-tis

Importações

import 'ds-tis/css'
import { initComboboxes } from 'ds-tis/combobox'

initComboboxes()

Markup

<div class="ds-field">
  <label class="ds-field__label" for="country">País</label>
  <div class="ds-combobox-anchor">
    <div class="ds-combobox ds-combobox--md">
      <input id="country" class="ds-combobox__input" role="combobox" aria-expanded="false" aria-controls="country-list" aria-autocomplete="list" />
      <button class="ds-combobox__clear" type="button" aria-label="Limpar seleção">…</button>
    </div>
    <ul id="country-list" class="ds-combobox__listbox" role="listbox" hidden>
      <li class="ds-combobox__option" role="option">Brasil</li>
    </ul>
  </div>
</div>

Contrato da implementação Web

Mapeamento de tokens

Propriedade	Token Component	Variável CSS
field surface	component.field.*	--ds-field-*
height	component.combobox.height.{sm|md|lg}	--ds-combobox-height-*
padding	component.combobox.padding-x.*	--ds-combobox-padding-x-*
listbox	component.combobox.listbox.container.*	--ds-combobox-listbox-*
option	component.combobox.option.* + component.menu.item.*	--ds-combobox-option-*
focus ring	component.focus-ring.*	--ds-focus-ring-*

Classes CSS

Classe	Descrição
ds-combobox	Wrapper do field
ds-combobox__input	Input editável com role="combobox"
ds-combobox__listbox	Container popup das opções
ds-combobox__option	Item do listbox (role="option")
ds-combobox__icon	Ícone leading opcional (Lucide)
ds-combobox__clear	Botão para limpar seleção
ds-combobox__chevron	Indicador decorativo do popup
ds-combobox--sm/md/lg	Tamanhos 32 / 40 / 48px
ds-combobox--error	Estado de erro
ds-combobox--disabled	Estado desabilitado
ds-combobox--readonly	Somente leitura — valor visível sem edição
ds-combobox--filled	Valor preenchido

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

Inicialize o runtime público após o render e destrua-o quando a view responsável for desmontada.

Evidência de validação

Coberta pelo Storybook estável, testes do runtime público quando aplicável, cenários de teclado, responsividade e Axe.

Abrir referência estável