Combobox

Quando usarWhen to use

Use Combobox quandoUse Combobox when

O usuário precisa digitar para filtrar opções, escolher de listas longas ou editar o valor antes de confirmar a seleção. The user needs to type to filter options, choose from long lists, or edit the value before confirming selection.

Não use Combobox quandoDon't use Combobox when

Menos de 5 opções fixas — prefira Radio. Lista fechada sem busca — use Select. Menu de ações — use Menu. Fewer than 5 fixed options — prefer Radio. Closed list without search — use Select. Action menus — use Menu.

AnatomiaAnatomy

Country

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). 1 Field (.ds-combobox) — wrapper with input, icon, clear, and chevron.
2 Input (.ds-combobox__input) — editable text with role="combobox".
3 Icon (.ds-combobox__icon) — optional, decorative.
4 Listbox (.ds-combobox__listbox) — popup with filterable options.
5 Option (.ds-combobox__option) — selectable item with role="option".
6 Label and helper — external via ds-field (ADR-017).

PadrãoDefault

Country

Type to filter countries.

<div class="ds-field">
  <label class="ds-field__label" for="country">Country
    <span class="ds-field__required" aria-hidden="true">*</span>
  </label>
  <div class="ds-combobox-anchor">
    <div class="ds-combobox ds-combobox--md">
      <input class="ds-combobox__input" id="country" type="text" role="combobox"
             aria-expanded="false" aria-controls="country-list"
             aria-autocomplete="list" placeholder="Choose a country"
             aria-describedby="country-helper">
      <i data-lucide="chevron-down" class="ds-combobox__chevron ds-icon" aria-hidden="true"></i>
    </div>
    <ul class="ds-combobox__listbox" id="country-list" role="listbox" hidden>…</ul>
  </div>
  <p class="ds-field__helper" id="country-helper">Type to filter countries.</p>
</div>

Listbox abertoOpen listbox

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. Compose with ds-field for label, helper, and error. Wrap .ds-combobox and .ds-combobox__listbox in .ds-combobox-anchor to position the popup. The public ds-tis/combobox module (initComboboxes / destroyComboboxes) is required for open state, filtering, selection, and keyboard. Event: ds-combobox-change.

Country

Type to filter countries.

<div class="ds-field">
  <label class="ds-field__label" for="country">Country</label>
  <div class="ds-combobox-anchor">
    <div class="ds-combobox ds-combobox--md ds-combobox--filled ds-combobox--open">
      <input class="ds-combobox__input" id="country" type="text" role="combobox"
             aria-expanded="true" aria-controls="country-list" aria-autocomplete="list">
      <i data-lucide="chevron-down" class="ds-combobox__chevron ds-icon"></i>
    </div>
    <ul class="ds-combobox__listbox" id="country-list" role="listbox">
      <li class="ds-combobox__option" role="option" aria-selected="true">Brazil</li>
    </ul>
  </div>
  <p class="ds-field__helper">Type to filter countries.</p>
</div>

TamanhosSizes

<div class="ds-combobox ds-combobox--sm">...</div>
<div class="ds-combobox ds-combobox--md">...</div>
<div class="ds-combobox ds-combobox--lg">...</div>

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`

EstadosStates

Error

Country

Please select a country.

<div class="ds-field ds-field--error">
  <div class="ds-combobox ds-combobox--error">
    <input class="ds-combobox__input" aria-invalid="true" aria-describedby="err">
  </div>
  <span class="ds-field__error" id="err">Please select a country.</span>
</div>

Disabled

<div class="ds-combobox ds-combobox--disabled">
  <input class="ds-combobox__input" disabled>
</div>

Read-only

<div class="ds-combobox ds-combobox--md ds-combobox--readonly ds-combobox--filled">
  <input class="ds-combobox__input" readonly value="Brazil" aria-label="Country (read-only)">
</div>

API no FigmaFigma API

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.The live component set composes the shared field (ADR-019) with a local listbox. State covers Default, Hover, Focus, and Disabled; Filled, Error, and Read-only are separate properties, like Select.

PropriedadeProperty	TipoType	Equivalente no repoRepo equivalent
`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`

Boas práticasBest practices

Faça

Permita busca por digitação e destaque a opção selecionada com aria-selected="true".Allow type-ahead search and mark the selected option with aria-selected="true".

Não faça

Não use combobox para escolhas booleanas — use Toggle ou Radio.Don't use combobox for boolean choices — use Toggle or Radio.

Diretrizes de conteúdoContent guidelines

RegraRule	ExemploExample
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>`

Mapeamento de tokensToken mapping

PropriedadeProperty	Token Component	Variável CSSCSS variable
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 CSSCSS classes

ClasseClass	DescriçãoDescription
`ds-combobox`	Wrapper do fieldField wrapper
`ds-combobox__input`	Input editável com `role="combobox"`Editable input with `role="combobox"`
`ds-combobox__listbox`	Container popup das opçõesOptions popup container
`ds-combobox__option`	Item do listbox (`role="option"`)Listbox item (`role="option"`)
`ds-combobox__icon`	Ícone leading opcional (Lucide)Optional leading icon (Lucide)
`ds-combobox__clear`	Botão para limpar seleçãoClear selection button
`ds-combobox__chevron`	Indicador decorativo do popupDecorative popup indicator
`ds-combobox--sm/md/lg`	Tamanhos 32 / 40 / 48px32 / 40 / 48px sizes
`ds-combobox--error`	Estado de erroError state
`ds-combobox--disabled`	Estado desabilitadoDisabled state
`ds-combobox--readonly`	Somente leitura — valor visível sem ediçãoRead-only — visible value without editing
`ds-combobox--filled`	Valor preenchidoFilled value

Interação por tecladoKeyboard interaction

TeclaKey	AçãoAction
`Arrow Down` / `Arrow Up`	Move o foco entre opções no listbox abertoMoves focus between options when listbox is open
`Enter`	Seleciona a opção focada e fecha o listboxSelects focused option and closes listbox
`Escape`	Fecha o listbox e retorna foco ao inputCloses listbox and returns focus to input
Typing	Filtra opções (implementação do produto)Filters options (product implementation)

AccessibilityAccessibility

Critério WCAGWCAG criterion	RequisitoRequirement	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`Label via `ds-field`; error with `aria-invalid` + `aria-describedby`	✓
2.4.11 Focus Appearance (AA)	Focus ring visível no field e nas opçõesVisible focus ring on field and options	✓

Quando usarWhen to use

AnatomiaAnatomy

PadrãoDefault

Listbox abertoOpen listbox

TamanhosSizes

EstadosStates

Error

Disabled

Read-only

API no FigmaFigma API

Boas práticasBest practices

Diretrizes de conteúdoContent guidelines

Mapeamento de tokensToken mapping

Classes CSSCSS classes

Interação por tecladoKeyboard interaction

AccessibilityAccessibility

RelacionadosRelated