Lists

Designing with lists

When screen readers encounter a list, they declare useful information sighted users realize at a glance: the presence of a list and the number of items in the list. However, to be recognizable and navigable to screen reader users, the list must use the appropriate semantic markup.

HTML provides three list structures, each with specific semantics:

• Use unordered lists (<ul>) when the order of the items is irrelevant. Each list item (<li>) in an unordered list is marked with a bullet.
• Use ordered lists (<ol>) for sequential information. Each list item (<li>) is numbered by the browser.
• Use description lists (<dl>) to group related terms (<dt>) and their descriptions (<dd>).

Individual list items can contain a variety of HTML elements, including paragraphs, headings, form elements, and other (nested) lists -- any kind of “flow content”.

Avoid nesting multiple child elements in each list item, since screen reader users can lose track of the list itself.

Unordered lists are commonly used to hold horizontal and vertical menus (for navigation, social media and list of links). Ordered lists are commonly used for breadcrumbs.

Unordered list

The unordered list consists of one <ul> element and multiple list item (<li>) elements:

HTML

Code begins

<ul>
   <li>Corn</li>
   <li>Tomatoes</li>
   <li>Beans</li>
   <li>Onions</li>
   <li>Garlic</li>
</ul>

Code ends

Ordered list

The ordered list consists of one <ol> element and multiple list item (<li>) elements:

Use ordered lists (<ol>) for sequential information, when the order of the items is relevant. Each list item (<li>) is numbered by the browser.

HTML

Code begins

<ol>
   <li>Cook beans for 45 minutes.</li>
   <li>Cut vegetables in small cubes.</li>    
   <li>Sauté onions and garlic.</li>
   <li>Deglaze using the tomatoes.</li>
   <li>Add corn and beans.</li>
</ol>

Code ends

Nested lists

Every list can be nested into another list. In the following example, the order of preparation is not critical, but the preparation itself should be done before using the ingredients. The information is still easy to digest, assistive technology can easily inform users about the number of steps.

HTML

Code begins

<ol>
   <li>Prepare ingredients
      <ul>
         <li>Cook beans for 45 minutes.</li>
         <li>Cut vegetables in small cubes.</li>
      </ul> 
   </li>
   <li>Sauté onions and garlic.</li>
   <li>Deglaze using the tomatoes.</li>
   <li>Add corn and beans.</li>
</ol>

Code ends

Description list

A description list consists of one or more term and description groupings. Each grouping associates one or more terms (the contents of <dt> elements) with one or more descriptions (the contents of <dd> elements).

A grouping begins either on the first item of the list or whenever a <dt> element follows an <dd> element.

<dl>  
   <dt>Authors</dt>
   <dd>John</dd>  
   <dd>Luke</dd>
   <dt>Editor</dt>  
   <dd>Frank</dd>
</dl>

dt { font-weight: 700; }
dd { margin-left: 30px; }

<dl>
   <dt>Producer</dt> 
   <dt>Director</dt>
   <dd>Ian</dd>  
   <dt>Writer</dt>
   <dd>Annie</dd>
</dl>

dt { font-weight: 700; }
dd { margin-left: 30px; }

<dl>
   <dt>Authors</dt> 
   <dt>Editors</dt>
   <dd>John</dd>  
   <dd>Luke</dd>
</dl>

dt { font-weight: 700; }
dd { margin-left: 30px; }

<dl>   
   <dt><dfn lang="en-US">color</dfn></dt>
   <dt><dfn lang="en-GB">colour</dfn></dt>
   <dd>A sensation which (in humans) derives from the ability of the fine structure of the eye to distinguish three differently filtered analyses of a view.</dd>
</dl>

dt { font-weight: 700; }
dd { margin-left: 30px; }

Related WCAG resources

The description of the three list types is from the Web Accessibility Initiative (WAI) document: Content Structure (WAI) in the Page Structure Tutorial of the Web Accessibility Tutorials. Eric Eggert, Shadi Abou-Zahra, eds. Copyright © 2019 W3C® (MIT, ERCIM, Keio). Status: Updated 27 July 2019. https://www.w3.org/WAI/tutorials/page-structure/content/