Results / Headless UI

Headless UI combobox

100% against @headlessui/react@2.2.10. Every check below cites the clause it measures, and every failure carries the command that reproduces it.

Reproduce this whole run

Serve the adapter from a clone of the repository, then:

npx @railing-dev/runner run --target headlessui --component combobox \
  --repeat 3 \
  --base-url http://localhost:5180

Or replay it without running anything: download the Playwright trace and open it with npx playwright show-trace.

The combobox has an accessible name

Check: combobox.has-accessible-name
Status: pass
Severity: serious
Why it matters: Without a name, a screen reader announces an unlabelled combobox and the user has no idea what they are choosing.
Measured against: APG pattern · WCAG 4.1.2 Name, Role, Value

The input exposes role=combobox

Check: combobox.has-combobox-role
Status: pass
Severity: serious
Why it matters: The role is what tells assistive technology that this input has a popup, and enables the announcements and shortcuts that go with it.
Measured against: APG pattern · WCAG 4.1.2 Name, Role, Value

The combobox can be reached with the Tab key

Check: combobox.is-focusable
Status: pass
Severity: blocker
Why it matters: If Tab does not reach it, a keyboard user cannot use the control at all.
Measured against: APG pattern · WCAG 2.1.1 Keyboard

aria-expanded is present and false before the popup opens

Check: combobox.collapsed-by-default
Status: pass
Severity: moderate
Why it matters: aria-expanded is how a screen reader announces that this control has a popup and that it is currently shut. Omitting it until opening leaves the user unaware there is anything to open.
Measured against: APG pattern · WCAG 4.1.2 Name, Role, Value

Down Arrow opens the popup

Check: combobox.opens-on-down-arrow
Status: pass
Severity: blocker
Why it matters: Down Arrow is the APG-specified way to open the list. If it does nothing, a keyboard user has no way to browse the options.
Measured against: APG pattern · WCAG 2.1.1 Keyboard

aria-expanded becomes true when the popup opens

Check: combobox.expanded-state-communicated
Status: pass
Severity: serious
Why it matters: A sighted user sees the list appear. Without the state change, a screen reader user is never told it did.
Measured against: APG pattern · WCAG 4.1.2 Name, Role, Value

Each option exposes role=option

Check: combobox.options-have-option-role
Status: pass
Severity: serious
Why it matters: Without the option role, a screen reader cannot count the choices, announce position within them, or let the user jump between them.
Measured against: APG pattern · WCAG 4.1.2 Name, Role, Value

Down Arrow moves through the options

Check: combobox.arrow-moves-active-option
Status: pass
Severity: blocker
Why it matters: Browsing the list is the entire purpose of the control. If the arrow keys do not move between options, a keyboard user cannot reach anything but the first.
Measured against: APG pattern · WCAG 2.1.1 Keyboard

The active option is exposed to assistive technology

Check: combobox.active-option-communicated
Status: pass
Severity: serious
Why it matters: A sighted user sees the highlight move. Unless it is communicated through aria-activedescendant or DOM focus, a screen reader user is never told which option they are on.
Measured against: APG pattern · WCAG 4.1.2 Name, Role, Value

DOM focus stays on the combobox while the popup is open

Check: combobox.focus-remains-on-combobox
Status: pass
Severity: moderate
Why it matters: The APG pattern keeps focus on the input so the user can keep typing to filter while browsing. Moving focus into the list breaks that and is a common source of confusing behaviour.
Measured against: APG pattern · WCAG 2.4.3 Focus Order

Enter selects the active option

Check: combobox.enter-selects-active-option
Status: pass
Severity: blocker
Why it matters: Selecting is the point of the control. If Enter does not commit the active option, a keyboard user can browse the list but never choose from it.
Measured against: APG pattern · WCAG 2.1.1 Keyboard

Escape closes the popup

Check: combobox.escape-closes
Status: pass
Severity: serious
Why it matters: Escape is the learned way out. Without it a user who opened the list by accident has no obvious way to dismiss it.
Measured against: APG pattern · WCAG 2.1.1 Keyboard

What this cannot tell you

A high score means no violations were detected by automated testing. It does not mean the component is accessible. Automated tests cannot judge whether a label is meaningful, whether a reading order makes sense, or whether the experience is usable with a screen reader. Those need human judgement and disabled users. This is a floor, not a ceiling.