# 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

```text
{
  "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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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