HTML Guide for listitem

To fix this issue, ensure that an element with role="listitem" is contained within an element with role="list" or role="group". Here’s how you can structure your HTML correctly:

Incorrect Example

<div role="listitem">Item 1</div>
<div role="listitem">Item 2</div>

Correct Example

<div role="list">
  <div role="listitem">Item 1</div>
  <div role="listitem">Item 2</div>
</div>

Alternatively, you can use role="group" if it’s a nested list.

Correct Example with Nested List

<div role="list">
  <div role="listitem">Item 1</div>
  <div role="group">
    <div role="listitem">Item 1.1</div>
    <div role="listitem">Item 1.2</div>
  </div>
  <div role="listitem">Item 2</div>
</div>

This ensures that the role="listitem" elements are correctly contained.

Using the ARIA role value listitem on an article element is invalid.

The article element is a landmark with an implicit role of article, and ARIA requires roles to match the element’s semantics. The listitem role is only valid for elements that are direct children of a list-type container with role list or group, or native lists like ul/ol. If you want an article in a list, wrap each article in a proper list container and either rely on native semantics (ul/ol) or use a neutral container with an explicit role="list". Avoid overriding landmark elements with unrelated roles. Use the role attribute only when necessary, and prefer native HTML semantics.

HTML Examples

Invalid: article with role=”listitem”

<article role="listitem">
  <h2>News item</h2>
  <p>Details...</p>
</article>

Valid options

<!-- Option A: Use native list semantics -->

<ul>
  <li>
    <article>
      <h2>News item</h2>
      <p>Details...</p>
    </article>
  </li>
  <li>
    <article>
      <h2>Another item</h2>
      <p>More details...</p>
    </article>
  </li>
</ul>

<!-- Option B: ARIA list with neutral containers -->

<div role="list">
  <div role="listitem">
    <article>
      <h2>News item</h2>
      <p>Details...</p>
    </article>
  </div>
  <div role="listitem">
    <article>
      <h2>Another item</h2>
      <p>More details...</p>
    </article>
  </div>
</div>

A <li> element is used to define an item of a list, so adding the listitem role to it is redundant.

The ARIA listitem role can be used to identify an item inside a list of items. It is normally used in conjunction with the list role, which is used to identify a list container.

<section role="list">
  <div role="listitem">List item 1</div>
  <div role="listitem">List item 2</div>
  <div role="listitem">List item 3</div>
</section>

When possible, you should use the appropriate semantic HTML elements to mark up a list and its list items — <ul> or <ol>, and <li>. For example:

<ul>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
</ul>