Fix guides · Accessibility

How to fix list markup (lists must only contain list items)

Lists with stray elements inside, list items without a list, and ARIA roles missing their parent or children. Why screen readers care and how to fix the markup.

Time to fix
15–30 minutes
Skill needed
Developer
Who notices
Screen reader users

Why it matters

Screen readers announce lists ("list, 5 items") and let users jump through them. That only works if the markup is right: <ul> and <ol> contain only <li>, and every <li> sits inside one.

The same idea applies to ARIA roles that come in families: a listbox needs options, a menu needs menu items, a tablist needs tabs, and each child needs its parent.

“When content elements other than list items are contained within a set of list elements, screen readers cannot inform the listener that they are listening to items within the list.”

Deque axe rule: list (used by Lighthouse)

Before you start

  • Your report shows each list or element that failed. Usually a <div> or <a> has been placed directly inside a <ul>, often by a menu or a slider.
  • Wrap the stray element in an <li>, or move it outside the list. For definition lists, <dl> may contain only <dt> and <dd> groups (optionally wrapped in <div>).
  • For ARIA roles, add the missing parent or child role, or switch to native HTML that already has the right structure.

Fix it on your platform

Shopify

  1. Menus, product grids and sliders in your theme are the usual source. Fix the markup in Edit code, or ask your theme developer.
  2. If an app's widget is listed, contact the app's developer.

WordPress

  1. Lists you create with the List block are correct. Check custom HTML blocks, menus and widgets from your theme or plugins.
  2. If a plugin's output is listed, update it or contact its developer.

Webflow

  1. Use the List and List Item elements together. A plain Div Block or Link placed directly inside a List breaks it; put it inside a List Item instead.
  2. For Collection Lists and Navbars, keep the structure Webflow creates.

Wix Managed by the platform

  1. Use the editor's bulleted or numbered list formatting for lists. If an app or your custom code is listed, fix or remove that code.

Squarespace Managed by the platform

  1. Use the text toolbar's bulleted and numbered lists. If code injection, a code block or an extension is listed, fix that code.

Next.js

  1. When mapping data to a list, render each item as an <li> directly inside the <ul>; put wrappers inside the <li>.
List
<ul>
  {products.map((p) => (
    <li key={p.id}>
      <ProductCard product={p} />
    </li>
  ))}
</ul>

Any other site

  1. Keep only <li> directly inside <ul> and <ol>, and only <dt>/<dd> inside <dl>.
HTML
<!-- Before -->
<ul>
  <a href="/shirts">Shirts</a>
</ul>

<!-- After -->
<ul>
  <li><a href="/shirts">Shirts</a></li>
</ul>

Check that it's fixed

  • Re-run your StudioLNC audit: the lists should no longer be listed.

Find every issue like this on your site

Free audit of performance, accessibility, SEO and security, with fixes for your platform.