Combobox

Componentes/Entrada e seleção

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

Componente Angular standalone com Angular Aria, filtro local, Form Field completo e ControlValueAccessor.

DesignUsoImplementaçãoAcessibilidade

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

Design

Preview funcional

Executado pelo componente Angular nativo com @angular/aria/combobox + listbox + Angular Forms.

Carregando preview funcional…

Abrir playground Angular

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

Quando escolher esta saída

Adote esta saída Angular nativa quando a aplicação já usa Angular. Ela consome o mesmo CSS do DS e não depende do runtime Web nem dos adapters React.

Implementação

Status

Beta

Distribuição

Tarball Angular validado

Instalação

npm

npm install ./dist/tis-angular-0.0.0-beta.0.tgz ds-tis

pnpm

pnpm add ./dist/tis-angular-0.0.0-beta.0.tgz ds-tis

yarn

yarn add ./dist/tis-angular-0.0.0-beta.0.tgz ds-tis

bun

bun add ./dist/tis-angular-0.0.0-beta.0.tgz ds-tis

Beta de workspace validada

O comando instala o tarball local gerado e validado no consumer. @tis/angular ainda não está publicado no registry público do npm.

Estilos do DS

@import "ds-tis/css";

Importações Angular

import { FormsModule } from '@angular/forms'
import {
  TisCombobox,
  TisComboboxIcon,
  type TisComboboxOption,
} from '@tis/angular/combobox'

Template

<tis-combobox
  name="country"
  label="País"
  [(ngModel)]="country"
  [options]="countryOptions"
  helperText="Digite para filtrar as opções."
  [required]="true"
>
  <svg tisComboboxIcon aria-hidden="true">…</svg>
</tis-combobox>

Contrato público

Pacote

@tis/angular

Entrypoint

@tis/angular/combobox

Primitive

@angular/aria/combobox + listbox + Angular Forms

Status

Beta

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 nativa do button, submit, nomes acessíveis, estado disabled e foco visível.

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