Code examples

Use semantic HTML

  • 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.
<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.

Use semantic HTML where possible

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.

Developer notes

Name

  • Inner text must describe the purpose

Role

  • <details> identifies as details
  • 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

  • Menus or 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.

Related expander accordion entries