The <details> Element
As defined in the HTML Living Standard, the <details> element represents a disclosure widget from which the user can obtain additional information or controls.
What is a disclosure widget?
It is an interactive element that toggles between an open and closed state, allowing users to show or hide content as needed.
<details>
<summary>Details Label</summary>
<p>This content is hidden until the user clicks the label.</p>
</details>
View HTML Living Standard: The details element
Relationship with <summary>
The <summary> element is the first child of a <details> element and provides a summary, caption, or legend for the widget.
- Interactive Trigger: The
<summary>is the part that the user clicks or activates with the keyboard to toggle the state. - Default State: By default, the widget is closed. Use the
openboolean attribute on the<details>tag to have it open on page load.
WCAG Requirement: Name, Role, Value
Success Criterion 4.1.2 (Level A): For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically determined.
Native <details> and <summary> tags satisfy this requirement automatically. Screen readers identify the element as a button or toggle, announce the text within the <summary> as its name, and correctly report the "expanded" or "collapsed" state to the user.
Usage Warnings
- No Nesting Interactivity: Do not place interactive elements like links or buttons inside the
<summary>tag. This confuses keyboard navigation and screen reader semantics. - Landmark Content: If the content inside a
<details>element is essential for understanding the page, ensure that hiding it behind a click is a conscious UX choice that doesn't hinder the user's primary path.
A11y Tip: Keyboard Access
Because the <summary> is natively keyboard-accessible, users can focus it using the Tab key and toggle it using Space or Enter. Avoid adding tabindex or custom key listeners, as they are unnecessary and can break native behavior.