Making accessible accordion

Learn how to create an accessible accordion that works for everyone, including users with disabilities.

An accessible accordion is a type of interactive component that allows users to expand and collapse content, while also providing a good user experience for people with disabilities.

Accordions reduce the need to scroll when presenting multiple sections of content on a single page. They should be accessible through keyboard navigation and follow WAI-ARIA roles, states, and properties guidelines for accessibility.

An accordion-like interface can be created by using a sequence of <details> elements, which are expanding sections that can reveal or hide content. As we’ll see later, using the name attribute allows these components to simulate the behavior of typical accordions, in which just a single section can be open at a time, with other sections closing themselves when a new one is expanded.

This solution does not involve JavaScript. Only HTML and CSS for styling.

What are the accessibility requirements for accordion?

To ensure an accordion’s accessibility, especially when building a custom accordion, one should follow these guidelines:

• Keyboard navigation: accordion headers should be focusable and navigable using the keyboard. Users should be able to open and close sections using keyboard interactions.
• WAI-ARIA roles, states, and properties: include ARIA roles and attributes such as role="button", aria-expanded, aria-controls. However, those aren’t needed when using <details> and <summary> HTML elements.
• Screen reader support: ensure that screen readers can announce the accordion headers, their corresponding sections, and state.
• Visual indicators: provide visual indicators, such as icons or colors, to show whether a section is expanded or collapsed. The <summary> element in HTML has a built-in marker that is displayed by default. This marker is a small triangle that indicates that the content can be expanded or collapsed.
• Focus management: manage focus on the accordion headers so that it is visible for the keyboard users.
• Semantic HTML: use semantic HTML elements, such as <details> and <summary> HTML elements.

Changing the default arrow on the summary HTML element

To change the default arrow on the summary HTML element, you can use CSS to hide the default arrow and add a custom arrow.

Use ::-webkit-details-marker and ::marker pseudo-elements to style the marker (or arrow) of a summary element in a details element.

The below CSS code example replaces the default marker (or arrow) of the <summary> element with a custom triangle and changes the triangle from a right-pointing triangle to a down-pointing triangle when the <details> element is open.

<style>
  details summary::-webkit-details-marker,
  details summary::marker {
    content: "";
    font-size: 0;
  }

  details summary::after {
    content: "\23F5";
    margin-left: 0.5rem;
  }

  details[open]>summary::after {
    content: "\23F7";
  }
</style>

Example implementation

<style>
  ul {
    list-style: none;
    margin: 0;
    max-width: 20rem;
    padding: 0;
  }

  ul li:not(:last-of-type) {
    margin-bottom: 1rem;
  }

  details {
    background: #f8f8f8;
    border: 1px solid #f0f0f0;
    border-radius: 0.3rem;
    padding: 0.5rem;
  }

  details p:last-of-type {
    margin-bottom: 0;
  }

  details summary {
    padding: 0.25rem 0.5rem;
  }

  .custom-details summary::-webkit-details-marker,
  .custom-details summary::marker {
    content: "";
    font-size: 0;
  }

  .custom-details summary::after {
    content: "\23F5";
    margin-left: 0.5rem;
  }

  .custom-details[open]>summary::after {
    content: "\23F7";
  }
</style>

<ul>
  <li>
    <details name="faq">
      <summary>Section 1</summary>
      <p>This is the content of section 1.</p>
    </details>
  </li>
  <li>
    <details name="faq">
      <summary>Section 2</summary>
      <p>This is the content of section 2.</p>
    </details>
  </li>
  <li>
    <details class="custom-details" name="faq">
      <summary>Section 3 with a custom arrow</summary>
      <p>This is the content of section 3.</p>
    </details>
  </li>
</ul>