details
The native HTML disclosure widget for expandable content. Creates an interactive widget that users can open and close without JavaScript.
Description
The <details> element creates a disclosure widget where the contents are visible only when toggled "open." It must contain a <summary> element as its first child, which provides the clickable label.
This is one of the few truly interactive HTML elements that works entirely without JavaScript. In Vanilla Breeze it serves as the foundation for several higher-level components: <accordion-wc>, <tab-set>, and tree navigation all build on native details/summary.
When to Use
- FAQ sections: Questions with expandable answers
- Collapsible content: Hide supplementary information by default
- Accordion patterns: Group related collapsible items
- Progressive disclosure: Reveal complex forms or options step by step
- Tree navigation: Collapsible menu sections (via
nav.tree) - Code examples: Optionally viewable source code
When Not to Use
- For modals or overlays — use
<dialog> - For dropdown menus with positioning — use
<drop-down>or<context-menu> - When content must always be visible — avoid hiding critical-path information
- When you need keyboard arrow navigation between panels — use
<accordion-wc>
Basic Usage
A single details element with a summary label. Use the open attribute to start expanded.
<details> <summary>Click to expand</summary> <p>This content is revealed when the details element is opened.</p></details><details open> <summary>Already expanded</summary> <p>This details element starts in the open state.</p></details>Stacked Details (Accordion)
Adjacent <details> elements automatically stack with connected borders — the border-radius is removed between siblings and the top border overlaps to prevent doubling.
<details> <summary>First item</summary> <p>Content for the first panel.</p></details><details> <summary>Second item</summary> <p>Content for the second panel.</p></details><details> <summary>Third item</summary> <p>Content for the third panel.</p></details>For enhanced keyboard navigation (Arrow Up/Down, Home/End) and ARIA attributes, wrap in <accordion-wc>.
Exclusive Accordion (name attribute)
The name attribute groups details elements so only one can be open at a time. This is a native browser feature requiring no JavaScript.
<details name="faq-exclusive" open> <summary>First Question</summary> <p>Only one panel can be open at a time...</p></details><details name="faq-exclusive"> <summary>Second Question</summary> <p>Opening this will automatically close the first panel.</p></details>Tip: The <accordion-wc> component also supports exclusive mode via data-single, adding keyboard navigation and View Transitions on top.
Rich Content
Details can contain any flow content: lists, definition lists, tables, images, and VB layout primitives.
As a Foundation for Web Components
In Vanilla Breeze, <details> / <summary> is the progressive enhancement base for two major web components. Both use the same HTML structure but add keyboard navigation, ARIA roles, and optional View Transitions.
accordion-wc
Wraps details elements with ARIA accordion keyboard navigation (Arrow Up/Down, Home/End) and optional data-single for exclusive mode.
<accordion-wc> <details open> <summary>Section One</summary> <p>Content for the first section.</p> </details> <details> <summary>Section Two</summary> <p>Content for the second section.</p> </details></accordion-wc>tab-set
Transforms details elements into a tabbed interface. Summaries become tab buttons in row 1, content panels display in row 2. Uses CSS display: contents on details for grid participation.
<tab-set> <details open> <summary>Tab One</summary> <p>Panel content for the first tab.</p> </details> <details> <summary>Tab Two</summary> <p>Panel content for the second tab.</p> </details></tab-set>Tree Navigation
The nav.tree variant uses nested details/summary for collapsible hierarchical menus. The nav context resets details styling and uses a +/− indicator instead of the chevron.
<nav class="tree" aria-label="File browser"> <details open> <summary>Documentation</summary> <details> <summary>Elements</summary> <ul> <li><a href="#">Buttons</a></li> <li><a href="#">Forms</a></li> </ul> </details> <details> <summary>Layout</summary> <ul> <li><a href="#">Grid</a></li> <li><a href="#">Stack</a></li> </ul> </details> </details></nav>See nav for more tree navigation variants.
CSS Reference
Base Styling
details { border: var(--border-width-thin) solid var(--color-border); border-radius: var(--radius-m);} /* Adjacent details connect their borders */details + details { margin-block-start: calc(var(--border-width-thin) * -1); border-start-start-radius: 0; border-start-end-radius: 0;} details:has(+ details) { border-end-start-radius: 0; border-end-end-radius: 0;} /* Content padding */details > :not(summary) { padding-inline: var(--size-m); padding-block-end: var(--size-m);}Open/Close Animation
Vanilla Breeze uses the ::details-content pseudo-element for smooth height animation. This is progressive — browsers that don't support it simply show/hide instantly.
/* Smooth open/close animation (Chrome 131+, Safari 17.5+) */::details-content { block-size: 0; overflow-y: clip; transition: block-size var(--duration-normal) var(--ease-default), content-visibility var(--duration-normal) allow-discrete;} details[open]::details-content { block-size: auto;}Context Overrides
Several contexts reset or extend the base details styling:
| Context | What Changes |
|---|---|
nav |
Removes border, border-radius, and content padding. Details used for grouping, not disclosure. |
nav.tree |
Replaces chevron with +/− indicator. Adds indentation for nested levels. |
accordion-wc |
Sets display: contents on details. Adds ARIA and keyboard navigation. |
tab-set |
Sets display: contents. Summary becomes tab button in grid row 1. |
@media print |
Forces all details open. Hides chevron markers. |
Print Behavior
In print stylesheets, all <details> content is forced visible regardless of the open attribute, so collapsed content is not lost when printing. The chevron indicator is hidden.
/* Print: force all details open, hide markers */@media print { details:not([open]) > *:not(summary) { display: block !important; } summary::after { display: none; }}Attributes
| Attribute | Type | Description |
|---|---|---|
open |
boolean | When present, the content is visible. Toggled by user interaction or JavaScript. |
name |
string | Groups details elements. Only one with the same name can be open at a time. |
JavaScript API
The <details> element can be controlled programmatically via the open property and the toggle event.
const details = document.querySelector('details'); // Check if openconsole.log(details.open); // true or false // Toggle programmaticallydetails.open = !details.open; // Listen for toggle eventsdetails.addEventListener('toggle', (event) => { console.log('Now', event.target.open ? 'open' : 'closed');});Events
| Event | Description |
|---|---|
toggle |
Fired when the open state changes. The open property reflects the new state. |
Accessibility
Built-in Accessibility
- The
<summary>element receives automatic button-like keyboard behavior - Screen readers announce the expanded/collapsed state
- Enter and Space keys toggle the state when summary is focused
Best Practices
- Always include a
<summary>as the first child - Keep summary text concise and descriptive
- Avoid nesting interactive elements inside
<summary> - Ensure hidden content is not critical path information
- For multiple related panels, consider
<accordion-wc>for keyboard arrow navigation between summaries
Keyboard Support
| Key | Action |
|---|---|
| Enter | Toggle open/closed when summary is focused |
| Space | Toggle open/closed when summary is focused |
Related
<summary>— Required clickable child that provides the toggle label<accordion-wc>— Enhanced accordion with Arrow/Home/End keyboard navigation and ARIA<tab-set>— Tab interface built on details/summary with grid layout<nav>— Tree navigation variant uses details for collapsible sections<dialog>— For modal overlays rather than inline disclosure
Patterns Using This Element
The <details> element is used across many patterns:
FAQ
Accordion-style questions and answers
Sidebar
Collapsible navigation sections
Wizard
Multi-step form disclosure
Checkout
Expandable checkout sections
App Shells
Collapsible application panels
Timeline
Expandable event details
Browser Support
The <details> element is supported in all modern browsers. The name attribute for exclusive accordions is supported in Chrome 120+, Safari 17.2+, and Firefox 130+. The ::details-content animation pseudo-element works in Chrome 131+ and Safari 17.5+; other browsers fall back to instant show/hide.