The details and summary elements

Definition

details creates a disclosure widget and summary provides its visible label. The open boolean attribute represents expanded state. The interaction works without application JavaScript.

Minimal syntax

<details>
  <summary>What should I bring?</summary>
  <p>Bring a laptop, charger, and a text editor you can use comfortably.</p>
</details>

The summary should be the first child and should describe what will be revealed, not use a vague label such as “More.”

Browser behavior

Activating the summary toggles open, updates the rendered content, and exposes state through accessibility APIs. Browsers supply a marker and keyboard behavior. CSS can style the disclosure, but removing every state cue makes it harder to understand.

Decisions and trade-offs

Use details for supplemental content a person can choose to reveal. Do not hide essential warnings, primary instructions, or critical search text solely to make a page look shorter. A button-controlled custom disclosure is appropriate only when the interaction needs behavior the native element cannot supply.

Accessibility

Keep the summary concise, visible, and focusable. Expanded content belongs immediately after it in reading order. Avoid placing complex interactive controls inside the summary itself, and confirm custom marker colors survive forced-color mode.

Common failures

• The summary says only “Details” or “Read more.”
• Essential task information is collapsed by default.
• CSS removes both native and replacement state indication.
• Nested interactive controls create ambiguous activation.
• Scripted synchronization changes open without preserving user state.

Verification checklist

Toggle with Enter, Space, pointer, and screen reader. Inspect the disclosure name and expanded state, then confirm hidden content is not focusable while closed. Test with JavaScript blocked, forced colors, reduced motion, 200% zoom, and 320-pixel reflow. Print or export the page if collapsed content must remain available in that output.

Maintenance note

Recheck disclosure labels when surrounding headings or content move. A summary that was once specific can become ambiguous when several similar disclosures appear together.

Also review whether the newly hidden content has become essential enough to remain expanded or visible.