How should list items be nested?


I am getting an automated scanner error that “<li> elements must be contained in a <ul> or <ol>”, but in my code the <li> elements are contained in <ul>. What’s going on?


Before diving into some technical causes, it’s important to evaluate the content. First, does the content actually function as a list? If not, the best solution is to code the content based on its purpose and function for users, which may involve removing the list markup entirely.

If the content is functioning as a list, there are a few different reasons why an automated scanner might flag this type of error. Most likely, either the list roles are being communicated incorrectly, or the parent-child relationship between the list and its list items is being disrupted.

Role Issue

The <ul> or <ol> element should communicate to the accessibility tree that it is a list, while the <li> elements it contains should communicate that they are list items. Missing or incorrect roles will interfere with how the lists are communicated to users on assistive technology.

For example:

<ul role="tabpanel"><li>Apples</li><li>Oranges</li></ul>

The <ul> element has role="tabpanel", which replaces the <ul> element’s native list role. This customization makes the list items (<li>) the children of a tabpanel, not a list, which can cause issues for users on assistive technology.

Parent-Child Issue

Another common cause for this error is if another element is in between the parent list (<ul> or <ol>) and its associated list items (<li>) in the DOM, thus disrupting their parent-child relationship.

For example:

<ul><div role="group"><li>Apples</li><li>Oranges</li></div></ul>

In this example, the insertion of a group element prevents the list items (<li>) from being direct children of the list container, so they may not be communicated well to users on assistive technology.

To correct these issues, the best remediation depends on the content’s functionality and context.

To learn more about close accessibility reviews and tailored recommendations from an Accessibility Specialist, explore the A11y Partner Program from Accessible Web.

Free Tools to Continue Learning

Accessible Web Company Logo

Accessible Web RAMP

Monitor your website and manage your progress towards WCAG conformance.

Accessible Web Company Logo

Accessible Web Academy

Career specific courses to help power up your accessibility knowledge.