Skip to content

Accessibility

The searchable dropdown follows the WAI-ARIA APG editable combobox with list autocomplete and meets WCAG 2.1 AA. Every field has a visible label and a clear focus indicator, every action works from the keyboard alone, and assistive technology hears the label, the state (disabled or error), the helper text and which option is highlighted — whether the user is looking at the list, listening to it, or typing into it.

  • All list items and states must keep accessible contrast on every supported surface. Source: WCAG 1.4.3 Contrast (Minimum).
  • Focus styles must stay visible, meet contrast requirements on every supported surface, and be clearly distinguishable from hover. Source: WCAG 2.4.7 Focus Visible.
  • Use semantic colour tokens (for example foreground/neutral/default) rather than fixed values, so the component adapts across themes and surfaces.
  • Interactive areas must be at least 44 px high. Source: WCAG 2.5.8 Target Size (Minimum).

The input is the only element that takes DOM focus. Typing filters the list and highlights the best match; the arrow keys move the highlight through the visible options, and Enter commits it. The highlighted option is announced through aria-activedescendant, so the list never receives focus and the user can keep typing at any moment. Only a listed value is accepted: on blur, free text falls back to the last selected option, and a required field left empty shows its error. The per-element roles, names and states are in Labelling elements below.

Key Action
Printable characters Type into the input, open the list and filter it; the best match is highlighted
↓ / ↑ Open the list, then move the highlight to the next / previous option, wrapping around
Alt + ↓ Open the list without moving the highlight
Enter Select the highlighted option and close the list
Escape Close the list; when it’s already closed, clear the input. Focus stays on the input
Space Type a space
Tab / Shift + Tab Close the list and move to the next / previous control

The field is a single tab stop: the input. The icon button sits outside the tab sequence and the options are reached with the arrow keys, not Tab. Selecting an option keeps focus on the input, now filled, and clicking outside closes the list without moving focus. Source: WCAG 2.4.3 Focus Order.

The Figma page describes a different keyboard model. These recipes follow the APG pattern instead, because it keeps the input editable at every step:

  • Tab through the options. Figma has Tab move through the list once it is open. Here, Tab leaves the field and closes the list; the arrow keys move through the options.
  • Space selects. Figma lets Enter or Space select the highlighted option. Here, Space types a space, since many values contain one; Enter selects.
  • The list receives focus. Figma moves focus into the list, to the selected or first option. Here, focus stays in the input and the highlighted option is conveyed with aria-activedescendant.
  • Escape returns to the previous element. Figma returns focus to the previous element on Escape. Here, Escape closes the list and focus stays on the input.

Input

A text <input> with role="combobox", aria-autocomplete="list", aria-controls pointing at the listbox, and aria-expanded kept in sync with the list. While an option is highlighted, aria-activedescendant holds its id. Name it with a <label for>; describe it with aria-describedby pointing at the helper text, or at the error message with aria-invalid="true" once validation fails. Set autocomplete="off" so the browser’s own suggestions don’t cover the list.

Icon button

A <button type="button"> with tabindex="-1", aria-expanded and aria-controls matching the input’s, and an aria-label naming the list ("Cities"). The chevron inside is aria-hidden="true".

Listbox

role="listbox" with an aria-label or aria-labelledby, so it doesn’t announce as an unnamed list.

Options

role="option" with a unique id, aria-selected="true" on the selected one and "false" on the rest. Each option takes its name from its text. Filtered-out options carry hidden, which also removes them from the accessibility tree.

No results

An option with aria-disabled="true", so it is announced but can’t be selected or highlighted.

Source: WCAG 4.1.2 Name, Role, Value.