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 the widget is toggled into an "open" state. 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, making it perfect for progressive enhancement patterns.

When to Use

  • FAQ sections: Show questions with expandable answers
  • Collapsible content: Hide supplementary information by default
  • Accordion patterns: Group related collapsible items together
  • Progressive disclosure: Reveal complex forms or options progressively
  • Mobile navigation: Create expandable menu sections
  • Code examples: Show code that users can optionally view

When Not to Use

  • For modals or dialogs - use <dialog> instead
  • For dropdown menus that need complex positioning - consider web component patterns
  • When content must remain visible - avoid hiding critical information

Basic Example

Click to expand

This content is revealed when the details element is opened. The summary acts as a clickable header that toggles the visibility of the content inside.

<details> <summary>Click to expand</summary> <p>This content is revealed when the details element is opened.</p> </details>

Variants

Open by Default

Use the open attribute to show content initially expanded.

Already expanded

This details element starts in the open state. Users can click to collapse it.

<details open> <summary>Already expanded</summary> <p>This details element starts in the open state.</p> </details>

Accordion (Stacked Details)

Adjacent <details> elements automatically stack with connected borders.

First item

Content for the first panel.

Second item

Content for the second panel.

Third item

Content for the third panel.

<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>

Exclusive Accordion (name attribute)

Use the name attribute to create an exclusive accordion where only one panel can be open at a time. This is a native browser feature requiring no JavaScript.

First Question

Only one panel can be open at a time when details elements share the same name attribute.

Second Question

Opening this will automatically close the first panel.

Third Question

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>

With Rich Content

View Product Details

This product includes the following features:

  • Feature one with detailed description
  • Feature two with benefits
  • Feature three with specifications
Weight 2.5 kg
Dimensions 30 x 20 x 10 cm

Styling the Marker

The default disclosure triangle is replaced with a custom chevron indicator. The styling hides the native marker and uses a CSS-generated arrow that animates on open.

CSS Implementation

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; } summary { /* Hide default marker */ list-style: none; /* Custom chevron indicator */ &::after { content: ""; inline-size: 0.5em; block-size: 0.5em; border-inline-end: var(--border-width-medium) solid currentColor; border-block-end: var(--border-width-medium) solid currentColor; transform: rotate(-45deg); transition: transform var(--duration-fast) var(--ease-default); } /* Hide WebKit default marker */ &::-webkit-details-marker { display: none; } } /* Rotate chevron when open */ details[open] > summary::after { transform: rotate(45deg); }

Attributes

Attribute Type Description
open boolean When present, the content is visible. Can be toggled by user interaction or JavaScript.
name string Groups details elements together. Only one with the same name can be open at a time.

JavaScript API

The <details> element can be controlled programmatically:

const details = document.querySelector('details'); // Check if open console.log(details.open); // true or false // Open the details details.open = true; // Close the details details.open = false; // Toggle details.open = !details.open; // Listen for toggle events details.addEventListener('toggle', (event) => { console.log('Details is 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
  • Arrow keys work naturally for navigation

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

Keyboard Support

Key Action
Enter Toggle open/closed when summary is focused
Space Toggle open/closed when summary is focused

Related Elements

  • <summary> - The required clickable child of <details>
  • <accordion-wc> - Enhanced accordion component with keyboard navigation and ARIA support
  • <dialog> - For modal overlays rather than inline disclosure

Browser Support

The <details> element is supported in all modern browsers. The name attribute for exclusive accordions has broad support in recent browser versions.