When designing web components, accessibility is paramount to ensure inclusiveness for all users, including those with disabilities. A common interactive element that greatly benefits from an accessible implementation is the accordion—a user interface component that allows users to expand and collapse content sections. In this tutorial, we will dive deep into building an accessible accordion using HTML description lists (<dl>).

Why Use Description Lists for Accordions?

HTML description lists (<dl>) are designed to pair terms and their descriptions, making them a natural fit for structuring an accordion.
Each term (<dt>) can serve as a clickable header, with its paired description (<dd>) acting as the collapsible content.
This semantic approach is not only meaningful for browsers and search engines but also improves accessibility when combined with proper ARIA attributes.

Structuring the Accordion with HTML

The backbone of our accordion is a <dl> element containing multiple <dt> and <dd> pairs:

<dl class="accordion">
  <dt>
    <button aria-expanded="false" aria-controls="section1" id="accordion1">
      Section 1
    </button>
  </dt>
  <dd id="section1" role="region" aria-labelledby="accordion1">
    <p>Content for section 1.</p>
  </dd>
  <dt>
    <button aria-expanded="false" aria-controls="section2" id="accordion2">
      Section 2
    </button>
  </dt>
  <dd id="section2" role="region" aria-labelledby="accordion2">
    <p>Content for section 2.</p>
  </dd>
</dl>

The buttons are linked to their respective content sections using aria-controls and aria-labelledby attributes, providing clear relationships for screen readers.

Adding Styles with CSS

Styling ensures that collapsed sections are hidden and expanded sections are clearly visible:

.accordion {
  border: 1px solid #ccc;
  border-radius: 4px;
  padding: 0;
  max-width: 400px;
}

.accordion button {
  width: 100%;
  padding: 10px;
  text-align: left;
  font-size: 16px;
  cursor: pointer;
  transition: background-color 0.3s;
}

.accordion dd {
  display: none;
  padding: 10px;
  background-color: #fafafa;
}

.accordion dd[aria-hidden="false"] {
  display: block;
}

Implementing Toggle Behavior with JavaScript

The following JavaScript snippet controls the expand/collapse behavior while maintaining accessibility attributes:

const buttons = document.querySelectorAll('.accordion dt button');

buttons.forEach((button) => {
  button.addEventListener('click', () => {
    const expanded = button.getAttribute('aria-expanded') === 'true';
    button.setAttribute('aria-expanded', !expanded);
    
    const content = document.getElementById(button.getAttribute('aria-controls'));
    content.setAttribute('aria-hidden', expanded ? 'true' : 'false');
  });
});

Enhancing Accessibility Further

To fully support accessibility, consider:

• Keyboard Navigation: Ensure users can navigate using Tab and activate with Enter/Space.
• Focus Management: Set appropriate focus states when expanding content.
• Screen Reader Announcements: Use aria-live for dynamic announcements.

Final Result

The full, working example can be seen at https://codepen.io/afixt/pen/vEBgYWy

See the Pen
Accessible Accordion Based on Description Lists (DL) by AFixt (@afixt)
on CodePen.

Learn More

For more tips and training on accessible web development, check out LearningAccessibility.com