- WAI-ARIA roles
ARIA: alert role
ARIA: application role
ARIA: timer role
ARIA: article role
ARIA: banner role
ARIA: button role
ARIA: cell role
ARIA: checkbox role
ARIA: Comment role
ARIA: Complementary role
ARIA: contentinfo role
ARIA: dialog role
ARIA: document role
ARIA: feed role
ARIA: figure role
ARIA: form role
ARIA: grid role
ARIA: gridcell role
ARIA: heading role
ARIA: List role
ARIA: listbox role
ARIA: Listitem role
ARIA: Main role
ARIA: Mark role
ARIA: Navigation Role
ARIA: Region role
ARIA: img role
ARIA: row role
ARIA: rowgroup role
ARIA: search role
ARIA: Suggestion role
ARIA: switch role
ARIA: tab role
ARIA: table role
ARIA: tabpanel role
ARIA: textbox role
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>
Description
Any content that consists of an outer container with a list of elements inside it can be identified to assistive technologies using the list
and listitem
containers respectively.
There are no hard and fast rules about which elements you should use to markup the list and list items, but you should make sure that the list items make sense in the context of a list, e.g. a shopping list, recipe steps, driving directions.
Warning: If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a list and its listitems β <ul>
/<ol>
and <li>
. See Best practices for a full example.
Associated WAI-ARIA Roles, States, and Properties
- list
-
A list of items. Elements with role
list
must have one or more elements with the rolelistitem
as children, a one or more elements with the role ofgroup
that have one or more elements with thelistitem
role as children. - group
-
A collection of related objects, limited to list items when nested in a list, not important enough to have their own place in a pages table of contents.
Keyboard Interactions
None.
Required JavaScript features
None.
Examples
ARIA Lists β some useful examples and thoughts by Scott O'Hara
Best practices
Only use role="list"
and role="listitem"
if you have to β for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript.
If at all possible, you should use the appropriate semantic HTML elements to mark up a list and listitems β <ol>
/<ul>
and <li>
. For example, our above example should be rewritten as follows:
<ul>
<li>List item 1</li>
<li>List item 2</li>
<li>List item 3</li>
</ul>
or use an ordered list if the order of the list items matters:
<ol>
<li>List item 1</li>
<li>List item 2</li>
<li>List item 3</li>
</ol>
Note: The ARIA list/listitem roles don't distinguish between ordered and unordered lists.
Note: If you are marking up a list of items that will function as a tabbed interface, you should instead use the tab
, tabpanel
, and tablist
roles.
Specifications
Specification | Status |
---|---|
Accessible Rich Internet Applications (WAI-ARIA) 1.1 The definition of 'listitem' in that specification. |
Recommendation |
Screen reader support
TBD