Combobox

Components/Input and selection

ImplementationHTML/CSS/JSArk/ZagReact · shadcn/Base UIAngular

A standalone Angular component with Angular Aria, local filtering, a complete Form Field, and ControlValueAccessor.

DesignUsageImplementationAccessibility

Documentation sectionDesignUsageImplementationAccessibility

Design

Functional preview

Running with the native Angular component and @angular/aria/combobox + listbox + Angular Forms.

Loading functional preview…

Open the Angular playground

Anatomy

Country * 6

1 2 3

• Brazil

4 5

Type to filter countries.

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

Default

Country*

Type to filter countries.

Open listbox

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*

• Argentina
• Brazil
• Chile
• Colombia (unavailable)

Type to filter countries.

Sizes

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

States

Error

Country*

Please select a country.

Disabled

Read-only

Figma API

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.

Property	Type	Repo 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

Usage

When to use

Use Combobox when

The user needs to type to filter options, choose from long lists, or edit the value before confirming selection.

Don't use Combobox when

Fewer than 5 fixed options — prefer Radio. Closed list without search — use Select. Action menus — use Menu.

Best practices

Faça

Allow type-ahead search and mark the selected option with aria-selected="true".

Não faça

Don't use combobox for boolean choices — use Toggle or Radio.

Content guidelines

Rule	Example
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>

Related

Select Input Menu Form Field

When to choose this output

Choose this native Angular output when the application already uses Angular. It consumes the same DS CSS and has no dependency on the Web runtime or React adapters.

Implementation

Status

Beta

Distribution

Validated Angular tarball

Installation

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

Validated workspace beta

The command installs the locally generated and consumer-tested tarball. @tis/angular is not published on the public npm registry.

DS styles

@import "ds-tis/css";

Angular imports

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>

Public contract

Package

@tis/angular

Entrypoint

@tis/angular/combobox

Primitive

@angular/aria/combobox + listbox + Angular Forms

Status

Beta

Accessibility

Keyboard interaction

Key	Action
Arrow Down / Arrow Up	Moves focus between options when listbox is open
Enter	Selects focused option and closes listbox
Escape	Closes listbox and returns focus to input
Typing	Filters options (product implementation)

Accessibility

WCAG criterion	Requirement	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; error with aria-invalid + aria-describedby	✓
2.4.11 Focus Appearance (AA)	Visible focus ring on field and options	✓

Output responsibility

Preserve native button semantics, submit behavior, accessible names, disabled state, and visible focus.

Validation evidence

Covered by its independent Storybook output plus browser, responsive, keyboard, Axe, and bundle checks.

Open the stable reference