Accessible widgets
A custom control built from plain elements must supply what the browser gives a native one: a role, its state and the expected keyboard behavior, plus a name. A strong answer walks the keystrokes and what a screen reader says.
What it is
A custom widget is an interactive control whose behavior the author scripts rather than getting it from the browser: a suggestion list under a search box, a tab strip, a tree, a menu. It may be built from div and span elements, or from a native input with a scripted popup attached. For native form elements the browser supplies keyboard handling, a role and states. For a component made accessible with ARIA, the attributes can supply the role and states, but not the keyboard handling; the author writes that in code and keeps the attributes true to what is on screen. The first rule of ARIA use says to reach for a native HTML element or attribute whenever one already has the semantics and behavior you need, instead of re-purposing an element and bolting a role onto it.
What assistive technology needs from any control is captured in WCAG success criterion 4.1.2, Name, Role, Value: software must be able to read the control's name and role, set the states and values a user can change, and learn when they change. For a search box with suggestions, the combobox pattern spells that out. The input has role="combobox", aria-expanded that is false while the popup is hidden and true while it shows, and aria-controls pointing at the popup. The popup has role="listbox" and each suggestion role="option"; the one shown as current carries aria-selected="true". aria-autocomplete="list" says the popup offers values that match what was typed. The name comes from a label element when the control is an input; otherwise from a visible element referenced by id or, with no visible label, aria-label.
<label for="q">Search</label>
<input id="q" type="text" role="combobox"
aria-autocomplete="list"
aria-expanded="true"
aria-controls="suggestions"
aria-activedescendant="opt-2">
<ul id="suggestions" role="listbox">
<li id="opt-1" role="option">laptop stand</li>
<li id="opt-2" role="option" aria-selected="true">laptop bag</li>
<li id="opt-3" role="option">laptop charger</li>
</ul>
<div aria-live="polite" class="visually-hidden">3 suggestions</div>Moving focus inside a composite control works one of two ways. With a roving tabindex, DOM focus really moves: the current item has tabindex="0", the other items tabindex="-1", and each arrow press swaps those values and calls focus() on the new item; the browser then scrolls it into view for you. With aria-activedescendant, DOM focus stays on the container (for a combobox, the input) and the attribute names the id of the item that counts as active. Assistive technology treats that item as the focused one and gets the same focus-change events it would get from a real focus move, while the author draws the focus ring and scrolls the item into view. The combobox pattern uses the second method, which is why someone can press Down Arrow to browse suggestions and then keep typing without going back to the field.
Updates the person needs to know about, but that happen away from focus, go in a live region. An element with aria-live="polite" is read out when the user pauses, without interrupting what they were doing and without receiving focus; assertive interrupts and may clear queued speech, so it is reserved for things that must be heard now. Screen readers generally announce changes to a live region, not its initial contents, so the region has to exist, empty, before you write the first result count into it; if script creates it, defer the first update to a later task. Behavior differs between browser and screen reader pairs, which is one reason to test with a real screen reader rather than trust the attributes.
When to use it
Build a custom widget when no native element gives the behavior: suggestions filtered as someone types, a tab strip, a tree, a grid with cell navigation. Then follow the published pattern for that widget rather than inventing keys. The patterns borrow conventions from desktop GUIs, so a screen reader user who hears "tree" expects Right Arrow to expand a branch, and the screen reader can even coach a new user on how to operate it because it knows what the element is. That payoff arrives when the keys match the pattern.
| Key | In the input | In the suggestion list |
|---|---|---|
Tab | Moves focus to the input; the list and its options are not in the Tab order | Leaves the widget |
Down Arrow | Moves into the popup, to the first option (or the one after an auto-selected suggestion) | Moves to and selects the next option; the W3C example wraps from last to first |
Up Arrow | Optional: moves to the last option | Moves to and selects the previous option |
Enter | Accepts a selected suggestion, cursor at the end of the value | Closes the popup and puts the option's text in the input |
Escape | Closes the popup; optionally clears the input if the popup was already closed | Closes the popup and returns focus to the input |
Printable character | Types it | Returns focus to the input, keeps the popup open, types the character |
Left and Right Arrow | Move the text cursor | Return focus to the input and move the cursor one character |
Manage focus whenever your code removes or hides the element that has it. If a dialog closes or a list item is deleted and nothing sets focus deliberately, the browser moves it to the body, which effectively means focus is lost: nothing visible shows where it is, and the person starts over. The guidance is to send focus to the button that opened the dialog, or to the item after the one deleted. Keep the indicator visible too: the default browser focus ring is the safe choice, and custom colors can vanish in high-contrast modes.
The bar for keyboard operation is WCAG 2.1.1: everything the interface does can be done from a keyboard, with the one exception of input that depends on the path of a movement, such as freehand drawing. Dragging an item to a new position is not exempt, because the end point is what matters, so a drag-and-drop list needs keys (or buttons) that move an item as well.
When not to
Skip the custom widget when a native element does the job. A select is exposed as a combobox in some browsers already, a button is focusable and fires on Enter and Space, and input type="search" is a perfectly good search field when there is no suggestion list. Developers are advised to prefer the semantic HTML element over ARIA when one exists, because native elements have keyboard access, roles and states built in. The saying "no ARIA is better than bad ARIA" has data behind it: in WebAIM's survey of over a million home pages, pages that used ARIA averaged 41% more detected errors than pages that did not.
Prefer a roving tabindex over aria-activedescendant when the items are controls in their own right, such as buttons in a toolbar or tabs, and when you want the browser to handle scrolling the focused item into view, which it does for a real focus move and not for an attribute change. aria-activedescendant also has strict rules about where the referenced element may sit in the DOM: a descendant of the focused element, something it owns through aria-owns, or, for a combobox, textbox or searchbox, something inside the element named by aria-controls.
Don't announce each keystroke. A polite region that reads the count after results settle is enough; an assertive one for routine updates tends to interrupt whatever the screen reader was saying. And don't intercept the browser's text-editing keys inside the input: Home, End, Left and Right Arrow and selection shortcuts belong to the browser. Down and Up Arrow are the keys the pattern takes for the popup, and the W3C guidance warns against capturing the editing keys in your key handler.
Compared
| Approach | How it works | Reach for it when | What it costs |
|---|---|---|---|
Native element | The browser supplies the role, states and keyboard handling | A | You accept the browser's look and behavior, or fight it |
Roving | DOM focus moves; one item has | Items are controls themselves (toolbar, tabs) and you want browser scrolling | You update |
| DOM focus stays on the container; the attribute names the active item | The person keeps typing while browsing options, as in a combobox | You draw the focus ring and scroll the item yourself; DOM placement rules apply |
Polite live region | Read when the user pauses; no focus change | Result counts, saved-state messages | Skipped if created with its content; varies by screen reader |
Assertive live region | Interrupts and may clear queued speech | An error the person must hear right now | Irritating for anything frequent |
In a picture
Step 1 of 4
Tab reaches the input
Tab lands on the search field, the one Tab stop in the widget. Because the input has a label and role="combobox", the screen reader can expose the label, the combobox role and the collapsed state; the exact wording differs between screen readers.
How to say it in an interview
The common mistake
Quiz
Questions that use this
Related
Sources
- W3C ARIA Authoring Practices Guide: Combobox Pattern
- W3C ARIA Authoring Practices Guide: Developing a Keyboard Interface
- W3C APG: Editable Combobox With List Autocomplete Example
- MDN: ARIA
- MDN: ARIA live regions
- MDN: ARIA: aria-live attribute
- Understanding SC 2.1.1 Keyboard (WCAG 2.2)
- Understanding Success Criterion 4.1.2: Name, Role, Value