Disclosure

Surfaces

Open in Storybook: Disclosure (opens in a new tab)

Overview

A disclosure shows and hides a block in place. It is details with summary: the browser supplies the role, the name, the expanded state, Enter and Space, and keeps closed content out of the Tab order and the accessibility tree. Script and ARIA only duplicate it.

The rule. details with summary as its first child and only control. No role, no aria-expanded, no aria-controls, no tabindex, no wrapper around the content. Focus stays on the summary when it opens. name on every member makes a one-open group; leave it off where people compare. A hidden marker owes a visible, aria-hidden replacement. Motion only under prefers-reduced-motion: no-preference.

Anatomy

Usage

Use cases

Seven recipes, each the real component and each working. They are the same two elements: only the name, the layout and the content change.

• FAQ

  One answer open at a time

  • Can I change my delivery date?

    Yes, until the order is packed. Open the order in your account and choose a new date.

  • How do I return a machine?

    Book a pickup from your account. We collect it within 3 working days, in the original box.

  • Do capsules expire?

    The best-before date is printed on every sleeve. Sealed, they keep for a year.

  details name="faq" · summary with an h3 · a marker

  Opening one closes the others, with no script. Focus stays on the question.

• Inline “read more”

  A detail folded into the sentence

  Grown at 1,800 m on volcanic soil, this Arabica is picked by hand and washed the same day

  Read more about the farm

  The beans dry on raised beds for twelve days and are turned by hand, which the family calls café de altura.

  display: inline on details, summary and [open]::details-content

  The name says what opens. Foreign words in the panel get their own lang.

• Spoiler · show solution

  An answer behind an explicit reveal

  Puzzle 4: which capsule has intensity 12?

  Show the solution

  Ristretto Intenso, the only sleeve printed with a 12.

  Closed content is out of view and out of the tree

  Nothing leaks to screen readers until it opens.

• Filter group

  Several groups, open to compare

  • Intensity

    1–56–910–13
  • Cup size

    Espresso · 40 mlLungo · 150 ml
  • Aromatic notes

    FruityWoodyCereal

  details per group, no name · fieldset aria-labelledby the summary

  Several stay open so people can compare.

• Spec in a card

  The spec sheet behind the price

  Vertuo Pop

  €99.00

  Technical specifications

  Water tank 0.6 l · 1260 W · 2.4 kg

  Cup sizes: 40, 80, 150, 230 ml

  No name · the summary is the only control in the card

  Card and disclosure stay separate: no stretched link over the card.

• Code or log fold

  A long block folded behind a count

  Changes in this order (2)

  - capsules: 10+ capsules: 12  intensity: 8

  A monospace panel in ::details-content · ins and del

  Diff lines with ins and del; the summary counts the changes.

• Narrow-screen groups

  The groups of a menu on a phone

  • Seeds

    • Vegetables
    • Flowers
    • Herbs
  • Plants

    • Indoor
    • Shrubs
    • Trees
  • Tools

    • Hand tools
    • Watering

  One details[name] per group · native keys only

  The menu panel’s narrow structure: same data, no arrow keys.

Props

Example

import { Disclosure, DisclosureList } from '@/components/Disclosure'

<DisclosureList name="faq">
  <Disclosure heading title="Can I change my delivery date?">
    <p>Yes, until the order is packed.</p>
  </Disclosure>
  <Disclosure heading title="How do I return a machine?">
    <p>Book a pickup from your account.</p>
  </Disclosure>
</DisclosureList>

Specs

Markup

<details>
  <summary>Shipping and returns</summary>
  <p>Free delivery from €40. Returns within 30 days, in the original box.</p>
  <p>Collection points close at 7 pm.</p>   <!-- direct children, no wrapper -->
</details>

<!-- A heading in summary keeps its level in the tree (DisclosureTriangle > heading 3) -->
<details>
  <summary><h3>Shipping and returns</h3></summary>
  <p>…</p>
</details>

<!-- Three or more in a row: a list, so the count is announced -->
<ul role="list">
  <li><details name="faq"><summary>Can I change my delivery date?</summary><p>…</p></details></li>
  <li><details name="faq"><summary>How do I return a machine?</summary><p>…</p></details></li>
  <li><details name="faq"><summary>Do capsules expire?</summary><p>…</p></details></li>
</ul>

Structure

Groups

The same name on every member: opening one closes the others, and closing the open one leaves none open (measured in Chromium 149 and WebKit 26.4). Exclusive hides one answer to show another, so it is for a FAQ and for the groups of a narrow menu. Leave it off where people compare, such as filters and specs.

Marker

Panel and motion

details::details-content {
  block-size: 0;
  padding-block: 0;
  padding-inline: 2.5rem 0.5rem;   /* the same open and closed */
  overflow: clip;
  opacity: 0;
}
details[open]::details-content { block-size: auto; padding-block: 0.85rem; opacity: 1; }
details > summary + * { margin-block-start: 0; }
details > :last-child { margin-block-end: 0; }

@media (prefers-reduced-motion: no-preference) {
  details { interpolate-size: allow-keywords; }
  details::details-content {                  /* closing */
    transition: block-size 0.25s var(--ease), padding-block 0.25s var(--ease),
      opacity 0.12s ease-out, content-visibility 0.25s allow-discrete;
  }
  details[open]::details-content {            /* opening */
    transition: block-size 0.3s var(--ease), padding-block 0.3s var(--ease),
      opacity 0.2s ease-out 0.05s, content-visibility 0.3s allow-discrete;
  }
  summary .marker { transition: rotate 0.25s var(--ease); }
}
details[open] > summary .marker { rotate: 90deg; }
/* --ease: cubic-bezier(0.4, 0, 0.2, 1) */

States

Tokens

Component tokens

Guidelines

Disclosure or something else?

Controls by scenario and context

Each row is a use case. A disclosure keeps its structure at every size: only spacing and wrapping change.

Accessibility

Keyboard

Focus

Screen readers

From the post, on real devices. The state is always read: never add it to the name.

Support

WCAG criteria

Related

This section is still in progress.

References

Read the post: Learn how to build a disclosure component using the native HTML details tag (opens in a new tab)