Code examples

Custom Expander Accordion (ARIA Disclosure Widget)

This custom expander uses a semantic button with aria-expanded with additional scripting to toggle content and states.

<div class="expander-group">
  <button class="expander-toggle" aria-expanded="false">
    About the NATO alphabet
  </button>
  <div class="expander-content">
    The (International) Radiotelephony Spelling Alphabet, 
    commonly known as the NATO phonetic alphabet, 
    is the most widely used set of clear code words 
    for communicating the letters of the Roman alphabet.
  </div>
</div>
The (International) Radiotelephony Spelling Alphabet, commonly known as the NATO phonetic alphabet, is the most widely used set of clear code words for communicating the letters of the Roman alphabet.

Native expander (details/summary)

  • This semantic HTML contains all accessibility features by default with no scripting required.
  • It uses CSS pseudo attributes to create the expanded/collapsed indicator, no Javascript.

Note: Due to known accessibility support issues in recent versions of iOS, <details> is not recommended for expander accordions. We recommend the use of an ARIA Disclosure Widget which has very robust support.

<details>
  <summary>
    About the NATO alphabet
  </summary>
  The (International) Radiotelephony Spelling Alphabet, 
  commonly known as the NATO phonetic alphabet, 
  is the most widely used set of clear code words 
  for communicating the letters of the Roman alphabet.
</details>
About the NATO alphabet The (International) Radiotelephony Spelling Alphabet, commonly known as the NATO phonetic alphabet, is the most widely used set of clear code words for communicating the letters of the Roman alphabet.

Developer notes

Name

  • Inner text must describe the purpose

Role

  • Native button identifies as button by default
  • Use role="button" for custom elements

Group

  • You can use aria-controls="popupId", but it is not well supported

State

  • Expanders use aria-expanded="true/false"

Focus

  • Focus must be visible

Design notes

  • Nielsen Norman Group study: The caret icon most clearly indicated to users that it would open an accordion in place, rather than linking directly to a new page.
  • Not all users will notice there is hidden content or understand how these work. For this reason, you should only use them in specific situations and if user research supports it.
  • ARIA Disclosure Widget