2024-08-13-mdn-html-details-exclusive-accordions.md

HTML-only exclusive accordions are here

Giving the same name to a group of <details> elements makes them behave like exclusive accordions. This is good news for developers who have been writing custom accordions from scratch because it’s soon supported across all major browsers. Let’s explore what this means with some quick examples.

This post is also published on the MDN Blog if you’d like to check it out there!

This feature’s stable in Chrome 120, Safari 17.2 and is enabled in Firefox Nightly, so you can already start trying it out. While you’re testing this out, be sure to read the accessibility concerns section.

# How does <details> work?

If you’re unfamiliar with <details>, it’s an element that creates a ‘disclosure widget’ in which information is visible only when the widget is toggled to an “open” state. You should include in it a <summary> element, which is used for the text describing the disclosure. If you omit the <summary>, a browser-specific string like “Details” will be used by default. Click the two elements below to toggle them between open and closed states and notice the missing <summary> in the first one:

<details>
  <p>
    The response phrase for 413 "Content Too Large" used to be "Payload Too
    Large", and this message is still widely used.
  </p>
</details>

<details>
  <summary>System configuration</summary>
  <ul>
    <li>200GB RAM</li>
    <li>4PB storage</li>
  </ul>
</details>

Since an accordion is a series of expandable sections that allow users to show or hide content, a series of <details> elements can be used to create an accordion-like interface. Using the name attribute, these elements can mimic “exclusive accordions”, meaning only one can be open and other sections automatically close when a new one is opened.

There’s great potential for <details> elements to fit into your pages because some minimal styling can go a long way to create interactive accordions using only HTML and CSS.

<details>
  <summary>System configuration</summary>
  <ul>
    <li>200GB RAM</li>
    <li>4PB storage</li>
  </ul>
</details>

<details>
  <summary>Recommended settings</summary>
  <ul>
    <li>Extreme mode: on</li>
    <li>Raytracing: enabled</li>
  </ul>
</details>

<details>
  <summary>Other details</summary>
  <ul>
    <li>Material: Faux Leather, Metal</li>
    <li>Item Weight: 10.2Kg</li>
  </ul>
</details>

# Using <details name> to create exclusive accordions

The addition of the name attribute lets you connect multiple <details> elements and make an accordion exclusive, so only one <details> element with the same name can be open at any time. The browser toggles all others with the same name to “closed”. It’s quite nice to be able to include this when you want to group multiple <details> elements:

<details name="tech-specs">
  <summary>System configuration</summary>
  <ul>
    <li>200GB RAM</li>
    <li>4PB storage</li>
  </ul>
</details>

<details name="tech-specs">
  <summary>Recommended settings</summary>
  <ul>
    <li>Extreme mode: on</li>
    <li>Raytracing: enabled</li>
  </ul>
</details>

<details name="tech-specs">
  <summary>Other details</summary>
  <ul>
    <li>Material: Faux Leather, Metal</li>
    <li>Item Weight: 10.2Kg</li>
  </ul>
</details>

An FAQ is one of the common uses, where the visitor can open one topic at a time:

<details name="faq">
  <summary>Can I request a refund?</summary>
  <p>
    Yes, you have up to 30 days to request a refund. See our T&C for details.
  </p>
</details>

<!-- etc. -->

# Accessibility concerns

Scott O’Hara, Eric Eggert and Adrian Roselli have all written multiple times about accessibility issues with this pattern. Notably, widgets can’t tell you how many disclosures there are and your current position within a group, nor can you ‘expand all’ and ‘collapse all’ widgets. Search is also not handled for collapsed widgets, so a CMD + F won’t match inside a collapsed widget. :weary:

Others, like HSBC Accessibility Hub and Florian Schroiff from A11Y Collective lists <details> and <summary> as a good implementation example and says they “offer a semantic and accessible solution with less code” so there are mixed opinions whether promoting this pattern is a good thing.

I lean towards Florian’s thoughts here, and that browsers should fill the gaps in poor and undefined behavior rather than hope good custom implementations propagate everywhere. There are a lot of ways to create this pattern, and I think our best bet is native browser behavior, which will probably be used off-the-shelf in most cases and reach the most amount of people.

These two examples were referenced in discussions if you want to have a look at accessible accordions that don’t use <details> and <summary>:

# That’s a wrap

With more support landing for this feature in more stable browsers, it’s a good indicator that the web platform is providing better functionality for features that web developers have had to write themselves. If you’re looking for a polyfill, there’s a great post by Bramus, which includes a polyfill for browsers that don’t support this yet.

Feel free to get in touch on Bluesky if you have any feedback or if you want to say hi. I hope you enjoyed this post and you’ll get more mileage out of the <details> element, which is a flexible and useful element for a lot of cases. Don’t get too lost in the <details> and see you next time!

# See also

If you want to learn more, you can have a read through these other resources:

Published: