Combobox
An input whose option list anchors beneath it with CSS anchor positioning. Filters as you type.
Examples
Combobox
Ada Lovelace Owner
Mika Kim Editor
Jun Rao Viewer
Anatomy
.combobox | Wrapper. Makes its .input the anchor for the list. |
> input.input | The text field, with role="combobox", aria-expanded and aria-controls pointing at the list. |
> .combobox-list | Frosted listbox, popover="manual". Anchors below the input at its width and flips above when there is no room. |
> [role=option] | One row per option: an avatar or icon, the label, and an optional <small> pushed to the end. |
API
| Attribute | Values | Description |
|---|---|---|
aria-selected | true | On an option: the highlighted row, with a fill and an accent edge at the start. aequitas.js moves it with the arrow keys. |
aria-expanded | truefalse | On the input: whether the list is open. aequitas.js keeps it in sync. |
aria-controls | <id> | On the input: the id of the .combobox-list. |
popover | manual | On the list. Required: the list is a popover, hidden until showPopover(). |
data-value | <text> | On an option: the value written into the input when it is picked. Default textContent. |
Behaviour
aequitas.js opens the list on focus and as you type, hides options whose text does not contain the input's value and highlights the first match; ↑/↓ move the highlight, and Enter or a click writes the option's data-value (or its text) into the input and fires change. Esc and blur close the list and aria-expanded follows. Without it, the list is a plain popover: open, filter and pick are up to you.
From aequitas.js. It initialises itself and enhances markup added later on its own, so it works the same in an SPA.
Accessibility
- Label the input with
<label for>, and give the listrole="listbox"withrole="option"rows. aequitas.js gives the inputrole="combobox",aria-expanded,aria-autocompleteandaria-controls(and the list anidif it has none); write them yourself without it. - Focus stays in the input; aequitas.js points
aria-activedescendantat the highlighted option (giving it anidif it has none), so screen readers announce it as it moves. - Set
autocomplete="off"so the browser's own suggestions do not cover the list.
| Key | Effect |
|---|---|
| ↓ / ↑ | Opens the list and moves the highlight through the visible options, wrapping at the ends. |
| Enter | Picks the highlighted option and closes the list. |
| Esc | Closes the list. Inside a dialog only the list: a second Esc closes the dialog. |