axe-core aria-required-children role combobox missing error

axe-core aria-required-children role combobox missing error - how to fix it

TL;DR

A combobox must own a listbox (and the listbox must own options). If you built a custom dropdown, add role listbox to the popup container and role option to each item, wired with aria-owns or DOM nesting. One line of why: the ARIA spec requires combobox to contain or own a listbox, and axe fails the widget when the required child role is missing.

The error, verbatim

{
  "id": "aria-required-children",
  "impact": "critical",
  "help": "Certain ARIA roles must contain particular children",
  "nodes": [
    { "target": [".custom-select"], "failureSummary": "Fix any of the following: Required ARIA child role not present: listbox" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules aria-required-children --save axe-combo.json

Expected: Violations array contains aria-required-children with the combobox selector in nodes.

Step 2: Inspect the widget structure

node -e "const r=require('./axe-combo.json'); const n=r.violations[0].nodes[0]; console.log(n.target.join(' '), n.html.slice(0,160))"

Expected: You see the combobox element and can confirm the popup div has no listbox role.

Step 3: Confirm the owned roles are missing

rg -n --glob '*.{jsx,tsx}' 'role=.listbox|role=.option' src/components/select | head -20

Expected: No output or only partial matches, confirming the popup items lack the required roles.

Step 4: Add the roles and re-scan

npx @axe-core/cli https://example.com --rules aria-required-children

Expected: Exit code 0, 0 violations. Keyboard test: arrow keys move through options and the screen reader announces the listbox.

Step 5: Gate the rule in CI

npx @axe-core/cli https://example.com --exit | tail -3

Expected: Non-zero exit while any violation remains; add this command to CI so the fix never regresses.

When to use this skill

• Your axe-core report lists this exact rule id under violations
• You are clearing automated WCAG 2.1 AA failures before a release or audit
• A CI a11y gate (pa11y-ci, lighthouse CI, cypress-axe) is red because of this rule

When NOT to use this skill

• The issue only shows up in manual screen-reader testing and axe reports zero violations for the rule
• You are doing a full manual WCAG audit, this skill covers the single automated rule only
• The page is a third-party embed you cannot edit, flag it to the vendor instead

Compatibility

axe-core 4.8+ (rule aria-required-children, WCAG 1.3.1 / 4.1.2). Same rule runs in axe-playwright, cypress-axe, and axe DevTools. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

required aria child role not present listbox

The failureSummary wording for combobox widgets missing their popup listbox.

custom dropdown axe combobox error

Practitioner phrasing: hand-rolled select components trip this constantly.

axe DevTools flags the same rule

The browser extension runs the same rule engine; fix once and it clears in every runner.

Why it happens

ARIA defines required owned elements per role, and combobox requires listbox (or tree, grid, dialog in the 1.2 pattern). Custom dropdowns usually get the combobox role and the expanded state right but render the popup as plain divs, so the ownership chain is broken. Axe checks the computed ownership including aria-owns, so even correctly nested markup fails if an intermediate wrapper breaks the parent-child role chain. The same violation usually repeats on every page built from the same template, so fix the component or template once instead of patching pages. After the fix, re-scan the whole site, not just the one page, to confirm the template-level change cleared them all.

Edge cases

• A combobox with aria-expanded false still needs the listbox present or owned, lazy-mounting the popup only when opened fails the scan.
• If you use aria-owns to wire a portaled popup, the owned element must exist in the DOM at scan time.
• Native select elements do not need any of this, if you can use a native select, do that instead of fixing the custom one.
• Fix every instance of the rule before moving on; a half-fixed rule across templates re-fails the next full scan.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bzpgqbG4YIY7SR8JS3Ueew