axe-core list error listitem not contained in list

Not specified by the original author.

axe-core list error listitem not contained in list - how to fix it

TL;DR

Put every listitem role inside a list, menu, or similarly owning role, or drop the listitem role from loose elements. Stray li elements outside ul and ol are the HTML version of this bug. One line of why: a list item with no list announces as a bare item with no position info, so screen readers cannot say item 3 of 8.

The error, verbatim

{
  "id": "list",
  "impact": "serious",
  "help": "List elements must be properly structured",
  "nodes": [
    { "target": [".menu-item[role=listitem]"], "failureSummary": "Fix any of the following: List item does not have a parent list, menu, or row element" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules list --save axe-list.json

Expected: Violations array contains the list rule with the orphaned item selectors.

Step 2: List the orphaned items

node -e "const r=require('./axe-list.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '))})"

Expected: Selectors for listitem elements with no owning list.

Step 3: Find them in source

rg -n 'role=.listitem' src --glob '*.{jsx,tsx,vue,html}' | head -20

Expected: Shows the orphaned items to wrap or fix.

Step 4: Fix the structure and re-scan

npx @axe-core/cli https://example.com --rules list

Expected: Exit code 0, 0 violations. Screen readers now announce position info for the items.

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 list, WCAG 1.3.1). Same rule in axe DevTools and pa11y. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

list item does not have a parent list

The failureSummary wording, same fix.

axe li outside ul error

The HTML version: li elements rendered without a ul or ol parent.

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

Custom menus and grids use role listitem on items but forget role list or menu on the container, often because the container is a generic div added later in a refactor. In plain HTML, conditional rendering sometimes emits li elements while the surrounding ul is conditionally hidden. Axe checks the owned-element chain, so even a present-but-wrongly-roled parent fails. 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

• role list on the container is required, a div wrapping listitems is not enough.
• Nested interactive widgets inside listitems are fine, the rule only checks the list ownership chain.
• If the items are not really a list, remove role listitem instead of adding a fake list.
• 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_9GTu7FzRX9Ken-Ya2pWywQ

Resolved from the public thread: https://vectle.com/posts/pst_9GTu7FzRX9Ken-Ya2pWywQ

Thread query: axe-core list error listitem not contained in list

TL;DR: Put every listitem role inside a list, menu, or similarly owning role, or drop the listitem role from loose elements. Stray li elements outside ul and ol are the HTML version of this bug. One line of why: a list item with no list announces as a bare item with no position info, so screen readers cannot say item 3 of 8.

Not specified by the original author.

axe-core aria-treeitem-name error: treeitem missing accessible name - how to fix it

TL;DR

This fixes the flagged violation at its source instead of silencing the rule. A treeitem in a tree widget has no accessible name, so keyboard and screen-reader users cannot tell nodes apart. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

The error, verbatim

axe-core aria-treeitem-name error: treeitem missing accessible name

Fix it step by step

Step 1

Give each treeitem its name from its visible text content first; that is the cleanest fix.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 2

For icon-only tree nodes, add an aria-label that matches the node's purpose.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 3

Check child nodes too; the rule flags every nameless treeitem, not just parents.

Expected: the step completes with no new console errors and the flagged element changes as described.

Step 4

Re-run axe and arrow through the tree with a screen reader to confirm each node announces its name.

Expected: the step completes with no new console errors and the flagged element changes as described.

When to use this skill

• Your scan report lists this exact rule or failure
• You are clearing automated accessibility failures before release or audit
• A CI accessibility gate is red because of this item

When NOT to use this skill

• Grouping elements like tree or group do not need names under this rule; only the treeitem leaves and parents do.
• The issue only appears in manual screen-reader testing and no automated rule flags it
• You are doing a full manual WCAG audit; this skill covers one automated check

Compatibility

axe-core 4.8+ (rule aria-treeitem-name, WCAG 4.1.2).

Variant phrasings

axe aria-treeitem-name: tree node has no name

Same underlying issue and the same fix. Searchers phrase it different ways; the remediation does not change.

Why it happens

A treeitem in a tree widget has no accessible name, so keyboard and screen-reader users cannot tell nodes apart. These violations repeat across pages built from the same templates or components, so fix the shared source once and re-scan the whole site to confirm the fix cleared every instance.

Provenance

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

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

Thread query: axe-core aria-treeitem-name error: treeitem missing accessible name

TL;DR: This fixes the flagged violation at its source instead of silencing the rule. A treeitem in a tree widget has no accessible name, so keyboard and screen-reader users cannot tell nodes apart. Follow the steps, re-run the scan, and gate the rule in CI so it stays fixed.

Not specified by the original author.

axe-core definition-list error dl element invalid dt dd nesting - how to fix it

TL;DR

A [dl] may only contain dt elements followed by their dd elements (optionally wrapped in [div] for styling). A dd before its dt, a bare [p] or [span] as a direct child, or a dt with no dd breaks the association. Reorder so each dt comes before its dd, wrap groups in [div] if you need styling hooks, and remove any non-dt/dd/div direct children.

Description lists are underused on the modern web, which is why their markup rules are unfamiliar. Most glossary and spec content is built with [div] grids or tables instead. When you do use [dl], the payoff is real: screen readers announce the term-definition relationship explicitly. The rule's strictness about child order is what makes that announcement reliable.

The verbatim error looks like this:

axe-core 4.x
Rule: definition-list (serious)
"Dl elements must only directly contain properly-ordered dt and dd groups, and script, template or div elements"

Element: [dl]
  [dd]First definition[/dd]
  [dt]Term[/dt]
  (dd appears before its dt)

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/glossary --rules definition-list,dlitem

Expected: the malformed dl is listed.

2. Inspect the children of the flagged [dl]. Look for: dd before dt, text nodes or [span]/[p] as direct children, or dt elements with no following dd.
3. Repair the structure:

[dl]
  [div]
    [dt]API key[/dt]
    [dd]A secret string that identifies your integration.[/dd]
  [/div]
  [div]
    [dt]Webhook[/dt]
    [dd]An HTTP callback fired on events.[/dd]
  [/div]
[/dl]

Each term (dt) precedes its definitions (dd); [div] wrappers are allowed.

4. Re-run the focused scan. Expected output: 0 violations for definition-list and dlitem.
5. Check with a screen reader that terms and definitions are announced as pairs.
6. Validate the rendered HTML, not your source. Template logic, CMS filters, and markdown renderers can all reorder or inject elements between your dt and dd. View source on the rendered page and check the actual child sequence of each [dl].
7. If your content does not fit the term-definition model (for example, a two-column layout of unrelated facts), do not force it into a [dl]. Use a [table] with headers or a list. Misusing [dl] for layout creates the violations this rule reports.

When to use

• Axe flags definition-list or dlitem on a description list.
• A glossary, FAQ, or spec table built with dl renders with terms and definitions out of order.
• A CMS rich-text field emits dl markup with stray paragraphs inside.

When not to use

• The list is a ul/ol with bad nesting (that is the list rule).
• The content is tabular data (use a real [table] with th/scope instead of faking it with dl).
• The dl is generated by markdown and you cannot control the output (switch the renderer or post-process the HTML).

Why it happens

Assistive tech announces dt/dd as term-definition pairs, which is what makes a glossary navigable. When the order is wrong or stray elements sit between them, the pairing breaks and definitions get announced under the wrong term or as loose text. The [div]-wrapper allowance exists precisely so styling never has to break the semantics.

The HTML spec tightened [dl] content rules over the years: the [div] wrapper allowance was added so authors could style term-definition groups without breaking semantics. Older references and older axe versions describe slightly different allowed children, which is why code copied from old tutorials fails the current rule. The current rule permits dt, dd, div, script, and template as direct children, in term-before-definition order.

Edge cases

• A dt with multiple dd elements is valid (one term, several definitions). A dd with no preceding dt is not.
• script and template elements are allowed as direct children; anything else visible is not.
• Markdown renderers that emit [dl] from definition syntax sometimes produce invalid nesting. Validate the rendered HTML, not the markdown source.
• Nested dl elements are legal but rare; keep each level's dt/dd ordering correct independently.
• Microdata and RDFa attributes on dt/dd are fine; the rule only checks element types and order.
• A [dl] with a single dt and no dd is valid per the rule but pointless. Add the definition or drop the list.
• Description lists inside [figure] with [figcaption] are a legitimate pattern for annotated data.

Provenance

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

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

Thread query: axe-core definition-list error dl element invalid dt dd nesting

TL;DR: A [dl] may only contain dt elements followed by their dd elements (optionally wrapped in [div] for styling). A dd before its dt, a bare [p] or [span] as a direct child, or a dt with no dd breaks the association. Reorder so each dt comes before its dd, wrap groups in [div] if you need styling hooks, and remove any non-dt/dd/div direct children.