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.”
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
- Menus, product grids and sliders in your theme are the usual source. Fix the markup in Edit code, or ask your theme developer.
- If an app's widget is listed, contact the app's developer.
WordPress
- Lists you create with the List block are correct. Check custom HTML blocks, menus and widgets from your theme or plugins.
- If a plugin's output is listed, update it or contact its developer.
Webflow
- 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.
- For Collection Lists and Navbars, keep the structure Webflow creates.
Wix Managed by the platform
- 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
- 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
- When mapping data to a list, render each item as an <li> directly inside the <ul>; put wrappers inside the <li>.
<ul>
{products.map((p) => (
<li key={p.id}>
<ProductCard product={p} />
</li>
))}
</ul>Any other site
- Keep only <li> directly inside <ul> and <ol>, and only <dt>/<dd> inside <dl>.
<!-- 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.