Skip to content

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.

On this page

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.

text
<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.

KeyIn the inputIn 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

ApproachHow it worksReach for it whenWhat it costs

Native element

The browser supplies the role, states and keyboard handling

A select, button, details or plain input gives the behavior you need

You accept the browser's look and behavior, or fight it

Roving tabindex

DOM focus moves; one item has tabindex="0", the rest -1

Items are controls themselves (toolbar, tabs) and you want browser scrolling

You update tabindex on each move; typing can't continue in a field

aria-activedescendant

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

Tab: focus inputReader: combobox

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

A suggestion list under a text field uses aria-activedescendant rather than moving DOM focus to each option. What does that buy the person using it?
Results arrive and your code inserts a new div with aria-live="polite" and the text "12 suggestions" in the same render. What is the likely outcome?
A keyboard user presses Escape to close a dialog and your code removes it from the DOM without setting focus. Where is focus now?
You need a field where someone picks one of eight fixed countries, no typing or filtering. What should you build?

Questions that use this

Related

Sources

  1. W3C ARIA Authoring Practices Guide: Combobox Pattern
  2. W3C ARIA Authoring Practices Guide: Developing a Keyboard Interface
  3. W3C APG: Editable Combobox With List Autocomplete Example
  4. MDN: ARIA
  5. MDN: ARIA live regions
  6. MDN: ARIA: aria-live attribute
  7. Understanding SC 2.1.1 Keyboard (WCAG 2.2)
  8. Understanding Success Criterion 4.1.2: Name, Role, Value
Sign in to report a mistake