Skip to main content
Beta: Front-End Checklist is currently in beta. Some issues are still being fixed. Thanks for your patience.

Use semantic list elements

Groups of related items use ul, ol, or dl elements so screen readers announce list context and item count.

Utilities
Quick take
Typical fix time 10 min
  • Use <ul> for unordered lists (navigation, features, bullets)
  • Use <ol> for ordered sequences (steps, rankings, instructions)
  • Use &lt;dl&gt; for term-definition pairs (glossaries, FAQs)
  • Screen readers announce 'list with X items' for proper lists
Why it matters: Screen readers announce list structure and item count—'list with 5 items'—helping users understand content organization. Styled divs provide no context.

Rule Details

Semantic list elements tell screen readers the content structure, enabling efficient navigation.

Code Example

<!-- ❌ Bad: Styled divs with no semantics -->
<div class="feature-list">
  <div class="feature">Fast performance</div>
  <div class="feature">Easy setup</div>
  <div class="feature">24/7 support</div>
</div>
 
<!-- ✅ Good: Semantic unordered list -->
<ul class="feature-list">
  <li>Fast performance</li>
  <li>Easy setup</li>
  <li>24/7 support</li>
</ul>

Why It Matters

Screen readers announce list structure and item count—'list with 5 items'—helping users understand content organization. Styled divs provide no context.

List Types

ElementUse ForAnnouncement
<ul>Unordered items"List with X items"
<ol>Ordered sequences"List with X items" + position
&lt;dl&gt;Term-definition pairs"Definition list"

Ordered Lists

<!-- ❌ Bad: Manual numbering -->
<div class="steps">
  <div>1. Sign up for an account</div>
  <div>2. Complete your profile</div>
  <div>3. Start using the app</div>
</div>
 
<!-- ✅ Good: Semantic ordered list -->
<ol class="steps">
  <li>Sign up for an account</li>
  <li>Complete your profile</li>
  <li>Start using the app</li>
</ol>

Definition Lists

<!-- ✅ Good: Term-definition pairs -->
<dl class="glossary">
  &lt;dt&gt;API</dt>
  &lt;dd&gt;Application Programming Interface</dd>
 
  &lt;dt&gt;REST</dt>
  &lt;dd&gt;Representational State Transfer</dd>
 
  &lt;dt&gt;JSON</dt>
  &lt;dd&gt;JavaScript Object Notation</dd>
</dl>
 
<!-- FAQ using definition list -->
<dl class="faq">
  &lt;dt&gt;How do I reset my password?</dt>
  &lt;dd&gt;Click the "Forgot Password" link on the login page.</dd>
 
  &lt;dt&gt;What payment methods do you accept?</dt>
  &lt;dd&gt;We accept Visa, Mastercard, and PayPal.</dd>
</dl>
<!-- ✅ Good: Navigation as list -->
<nav aria-label="Main navigation">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/products">Products</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/contact">Contact</a></li>
  </ul>
</nav>

React Component

interface ListProps {
  items: string[]
  ordered?: boolean
}
 
function List({ items, ordered = false }: ListProps) {
  const Tag = ordered ? 'ol' : 'ul'
 
  return (
    <Tag>
      {items.map((item, index) => (
        <li key={index}>{item}</li>
      ))}
    </Tag>
  )
}

CSS Styling

/* Remove default bullets while keeping semantics */
ul.clean-list {
  list-style: none;
  padding: 0;
  margin: 0;
}
 
/* Custom bullets with accessibility preserved */
ul.custom-bullets li::before {
  content: "✓";
  margin-right: 0.5em;
  color: green;
}

Exceptions

  • Evaluate the rendered experience before treating a static-code smell as a blocker; interaction timing, browser behavior, and assistive technology output often determine severity.
  • Not every secondary accessibility issue deserves equal weight; prioritize the issue that most directly blocks perception, operation, or understanding.
  • Avoid adding redundant markup or ARIA solely to satisfy a rule when a simpler semantic implementation would eliminate the issue entirely.

Verification

Automated Checks

  • Use browser accessibility tooling, axe, Lighthouse, or equivalent automated checks against a representative rendered state.

Manual Checks

  • Use screen reader to navigate lists
  • Verify "list with X items" announcement
  • Check item count matches visible items

Use with AI

Copy these prompts to use with your AI assistant, or install the MCP server to use directly from Claude, Cursor, or Windsurf.

Check

Verify implementation

Identify groups of related items (navigation menus, product features, steps) and verify they use ul, ol, or dl elements rather than divs or spans styled to look like lists.

Fix

Auto-fix issues

Wrap related items in appropriate list elements: ul for unordered lists, ol for numbered sequences, dl for term-definition pairs. Use li for list items and proper dt/dd for definition lists.

Explain

Learn more

Explain how screen readers announce 'list with X items' to help users understand content structure, and why styled divs provide no semantic information about grouped content.

Review

Code review

Review the rendered markup and interactive states that affect Use semantic list elements. Flag exact elements, roles, labels, focus behavior, or keyboard interactions that violate the rule, and note how to verify the fix with browser accessibility tooling or assistive tech.

Sources

References used to support the guidance in this rule.

Further Reading

Tools and supplementary material for exploring the topic in more depth.

axe DevTools
deque.comTool

Rules that often go hand-in-hand with this one.

Place list items within list containers

List item elements (li) must always be direct children of a list container (ul, ol, or menu) to maintain valid HTML structure and correct screen reader announcements.

Accessibility
Use correct definition list structure

Definition lists (&lt;dl&gt;) must only contain valid &lt;dt&gt; and &lt;dd&gt; elements.

Accessibility
Wrap definition items in a definition list

Description terms (&lt;dt&gt;) and details (&lt;dd&gt;) must be contained within a &lt;dl&gt; element.

Accessibility
Use correct list structure

Lists (ul, ol) should only contain list item elements (li) to ensure they are correctly interpreted by assistive technology.

Accessibility

Was this rule helpful?

Your feedback helps improve rule quality. This stays internal for now.

Loading feedback...
0 / 385