Build an accessible disclosure with details and summary

What you get for free

A disclosure is a button paired with a region it shows and hides. Write this:

<details>
  <summary>What is progressive enhancement?</summary>
  <p>Building so the core works without JS, then layering on enhancements.</p>
</details>

…and the browser hands you, at no cost:

• A focusable, keyboard-operable toggle — Enter and Space both work.
• Correct semantics: the <summary> is exposed as a button with an expanded/collapsed state, and screen readers announce it.
• An open attribute reflecting state, usable as a CSS hook.
• In-page-find that auto-expands matching content in modern browsers.

Styling without breaking it

The first thing everyone wants is to kill the default triangle marker. Do it with list-style, and replace it with your own indicator:

summary {
  list-style: none;          /* Firefox + others */
  cursor: pointer;
}
summary::-webkit-details-marker {
  display: none;             /* Safari/Chrome legacy */
}
summary::before {
  content: "";
  /* your own chevron — a mask-image icon that rotates on open */
}
details[open] summary::before {
  transform: rotate(90deg);
}

The key insight: drive your custom marker off the [open] attribute, not off JS state. The browser owns open; your CSS just reacts to it. That keeps the no-JS path fully working.

A common mistake is putting an interactive element inside <summary>:

The animation problem

Here’s where the native element fights you. You’d think this animates open:

details[open] { /* ...taller... */ }

It doesn’t. The content appears instantly because <details> toggles display, and display isn’t animatable in a way that interpolates height. People try several escape hatches:

The grid-template-rows: 0fr → 1fr trick is lovely — wrap the content in a grid track and transition the track from 0fr to 1fr:

.content-wrapper {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 200ms ease;
}
details[open] .content-wrapper { grid-template-rows: 1fr; }
.content-wrapper > * { min-height: 0; overflow: hidden; }

The wrinkle: when <details> loses open, the browser removes the content from the box immediately in some engines, cutting the close transition. The robust fix is a sliver of progressive enhancement — toggle a data-expanded attribute to run the transition, and hold the native open attribute until transitionend fires.

One disclosure vs a group

A single toggle is a disclosure. A group of them presented as one unit is an accordion — and “only one open at a time” is a property of the group, not of the toggle.

You might reach for the native grouping attribute, <details name="faq">, which makes a set mutually exclusive. It works, but its force-close is instant and skips your collapse animation. For an animated exclusive group, coordinate it in JS instead:

That’s exactly how this site’s MdDisclosure and MdAccordion components are built — native first, enhanced second.

Takeaways

• Start with <details>/<summary>. You get accessibility and keyboard support for free.
• Style the marker off the [open] attribute; never nest interactive elements in <summary>.
• Animation needs a small JS assist today for cross-browser close transitions — but the no-JS path keeps working.
• “One open at a time” is an accordion concern; animate it in JS rather than relying on <details name>.

The best component is often the one the platform already wrote for you.