- Docs
- Accessibility built in
Accessibility built in
The ARIA combobox pattern, keyboard support, status messages and what your markup still has to provide for an accessible search.
What the package provides
- The input becomes
role="combobox"witharia-autocomplete="list",aria-controlspointing to the generatedrole="listbox", andaria-expandedkept in sync. - The listbox is named by the input’s
<label>througharia-labelledby; a label without an id gets one, removed again ondestroy(). - Focus stays on the input. The active option is announced through
aria-activedescendantand marked witharia-selected, as in the WAI-ARIA editable combobox pattern. Options are non-focusablerole="option"elements, so they never become Tab stops. - Sections render as
role="group"elements named by their heading througharia-labelledby; arrow keys move through every option across groups. - The listbox only ever contains options and groups. Loading, empty and error messages are shown in a separate element outside it.
- A visually hidden polite live region (
role="status") announces the result count, the empty message and errors. Loading is shown but not announced, so fast typing stays quiet. - Header and footer content (
renderHeader,renderFooter) sits outside the listbox and is not part of arrow-key navigation, so focus stays on the input. Put keyboard-reachable actions in an option, or keep them reachable elsewhere on the page. - ArrowDown on an empty input opens the recent selections when
recentis enabled. - Matches are marked with
<mark>, which keeps the label text intact for screen readers. - Keys: ArrowUp/ArrowDown move, Home/End jump to the first and last option, Enter selects, Escape and Tab close the list.
- IME composition (Japanese, Chinese, Korean) is respected: the search waits until the composition ends.
destroy()restores the attributes it changed, including a pre-existingautocomplete.
What your page provides
- A visible
<label for>for the input. - Messages in the page’s language through
messages: { loading, empty, error, results }. Each is a string or a function of{ query, count }, so plurals and the typed query can be part of the announcement. - Enough contrast for the list colors if you override the
--autocomplete-*variables.