Skip to content

Combobox

An editable <input> with autocomplete (APG combobox pattern). You type to filter the list and pick an option, or—with data-ts-allow-custom on the root—keep a free-form value. Unlike the Select, the text field is the control.

Forms · TaishoDS Core, in plain HTML.

Examples

One working example per case. Each example is the HTML of its preview—copy it as is, and with Core’s CSS and JS loaded, it looks and works the same.

Search for a team member

html

Clearable with a value

html

Read-only

html

Compact density, with error

html

With search icon

html

Options grouped by role

html

Server-side search, loading

html

Inside a filters popover

html

With hint, icon, and description

html

Multiple owners

Ana Torres Carla Ruiz
html

Class reference

Every value of each modifier, with its HTML ready to copy.

Size

Field height: sm, md, or lg.

html

Variant

The border color for validation: default, success, warning, info, or danger.

html

Density

The field’s inner spacing: comfortable or compact.

html

States

is-loading shows the Spinner in the field and the panel’s Loading… (aria-busy) without blocking editing. is-readonly prevents editing but keeps the field focusable.

html

Combinations

Size and variant combined.

html

When to use

  • The list is long, and typing to filter is the natural way to reach an option.
  • The user might need a value that isn’t in the list (data-ts-allow-custom).
  • Autocompleting as they type saves more than opening a panel and scanning it.
  • You need to assign several values from a long or server-backed list, and it helps to see them in the field (data-ts-multiple).

When not to use

  • The list is short and known, so opening it and picking is enough → select.
  • You want a search box inside the panel, or to summarize several options as a count → select.
  • You’re not capturing a value but running app-wide commands → command-palette.

Do

  • Show a clear empty state when the filter finds nothing.
  • If you allow free-form values, make it obvious how to confirm a new one.

Don’t

  • Don’t use it for four options. For so few, the input adds more friction than a Select.
  • Don’t hide important options behind the filter without a visible default.

TaishoDS Core

Needs Core’s JS, which handles focus, keyboard, and state.

It’s a free-text field with live filtering and a list of options.

Core hooks into it through these attributes. They go in the markup, and there’s nothing to initialize.

  • data-ts-async
  • data-ts-clear
  • data-ts-combobox
  • data-ts-dismiss
  • data-ts-dismissible
  • data-ts-listbox
  • data-ts-listbox-empty
  • data-ts-listbox-input
  • data-ts-listbox-live
  • data-ts-listbox-loading
  • data-ts-listbox-panel
  • data-ts-listbox-spinner
  • data-ts-listbox-tag-template
  • data-ts-listbox-tags
  • data-ts-listbox-template
  • data-ts-listbox-toggle
  • data-ts-listbox-value
  • data-ts-multiple
  • data-ts-placeholder
  • data-ts-value

What it does: The APG combobox pattern on top of Select’s list, plus filtering as you type. Esc with the panel open doesn’t propagate to a Popover that contains it, and hovering an option makes it active. Groups (role="group" with aria-labelledby) are filtered by hiding the heading of any group left empty.

Attribute What it does
data-ts-allow-customOn the root. Accepts text that isn’t in the list as the value.
data-ts-listbox-toggleThe chevron as a button.
data-ts-clearThe clear button.
readonlyOn the input, as in any field.
density-compact, ts combobox-prefix-blockCompact density and prefix: markup and CSS.
data-select-option-icon, data-select-option-descriptionOptions with an icon and a description are static markup. The field shows only the label.
setComboboxLoading(root, true | false)Sets is-loading, aria-busy, the Spinner, and the “Loading…” message.
data-ts-asyncOn the root. Core doesn’t filter on the client (the server already did). Your app listens to ts:change and reads query.
form.reset()Returns to the initial value.

From the CDN, without a build, load taisho.combobox.css along with taisho.base.css. Also load:

  • taisho.button.css
  • taisho.checkbox.css
  • taisho.icon.css
  • taisho.spinner.css
  • taisho.tag.css
  • taisho.visually-hidden.css

For how Core works in general, see Behavior.

Accessibility

Implements the Combobox pattern from the WAI-ARIA APG.

  • The input is role="combobox" with aria-autocomplete="list", aria-expanded, and aria-controls pointing to the listbox.
  • Navigation: arrow keys to move through the options, Enter to select the focused one (or confirm the text), and Esc to revert and close.
  • aria-activedescendant points to the highlighted option, which the screen reader announces without moving focus out of the input. Hovering an option highlights it (and makes it the active one).
  • Options with a description are named by their label (aria-labelledby) and described with aria-describedby. The icon is decorative (aria-hidden). The field shows only the label.
  • The chevron is a <button tabindex="-1" aria-label="Show options"> (data-ts-listbox-toggle in Core). It opens or closes with the mouse or touch and stays out of the Tab order, because the keyboard already has the input and the arrow keys. The mouse doesn’t take focus away from the input.
  • The clear button (data-ts-clear) comes right after the input in the Tab order, has its own aria-label, and only shows with a value, without disabled, and without readonly. Activating it empties the value, and focus stays on the input.
  • readonly doesn’t open the panel with the mouse or the arrow keys. The input stays focusable and selectable, without the chevron or the clear button.
  • With the panel open, Esc closes it and doesn’t propagate to a Popover or Modal that contains the Combobox. With the panel closed, Esc reaches the container. form.reset() restores the initial value without firing the change event.
  • Options with a group go inside a role="group" named by its heading (aria-labelledby). The arrow keys move through the options in visual order, jumping from one group to the next. Headings aren’t options and don’t receive focus. When filtering, a group left with no options disappears along with its heading.
  • For async mode, call setComboboxLoading(root, true|false). It sets is-loading and aria-busy="true" on the input and the panel, plus a role="status" Spinner in the field. That’s the only announcement, so “Loading” isn’t repeated twice. In the panel, “Loading…” is visible text next to a decorative Spinner, because a listbox doesn’t allow children with role="status". While loading, “No results” isn’t shown, because it would be false. It doesn’t disable the input, so you can keep typing.
  • The prefix is decorative (an icon or avatar) and stays out of the Tab order. The input’s accessible name is still its label. Density (density-compact or density-comfortable) only changes the size. It doesn’t touch any ARIA attribute.
  • With multiple (data-ts-multiple in Core), the listbox carries aria-multiselectable="true" and each option its aria-selected. The checkbox is decorative (aria-hidden). Additions and removals are announced through an aria-live="polite" region, because focus doesn’t move when you pick. Each tag’s button is named after the value it removes. When you remove a tag with the keyboard, focus moves to the neighboring tag or, if none are left, to the input. required blocks submission only while there are no values. form.reset() restores the initial selection.

Keyboard

On top of what the browser already does (Tab moves focus, Enter activates a button).

Key What it does
↑↓Move through the filtered options.
EnterSelects the focused option, or confirms the typed text.
EscReverts to the previous value and closes.
Enter(multiple)Adds or removes the focused option without closing the panel. With no focused option, adds the typed text if it matches an option or free-form values are allowed.
Backspace(multiple)With an empty field, removes the last tag. With text, deletes text.
Tab(multiple)Moves through each tag’s remove button before reaching the field.

Verification

What was actually tested. Anything that wasn’t tested says so—we’d rather say “not verified” than claim too much.

  • axe WCAG 2.2 A + AA in a real browser, in light and dark mode, before every release.
  • keyboard Key map documented above, checked against the component.
  • screen reader Not verified with a screen reader. Test it in your own combination of components, not just here, where each one appears alone and on its happy path.