The details Element

Technical Deep Dive & Specifications

The WHATWG Specification & DOM Interface

According to the WHATWG HTML Living Standard, the <details> element represents a disclosure widget from which the user can obtain additional information or controls on demand.

The corresponding DOM interface is HTMLDetailsElement:

[Exposed=Window]
interface HTMLDetailsElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions] attribute boolean open;
  [CEReactions] attribute DOMString name;
};

The open Boolean Attribute

The state of the disclosure widget is governed by the boolean open attribute:

• Absence of open: The widget is closed. Only the <summary> child is rendered. All remaining sibling children inside <details> are hidden.
• Presence of open: The widget is open. Both the <summary> and all disclosed children are rendered in the layout.

<!-- Closed State -->
<details>
  <summary>System Diagnostics</summary>
  <p>CPU Temperature: 42°C</p>
</details>

<!-- Open State -->
<details open>
  <summary>System Diagnostics</summary>
  <p>CPU Temperature: 42°C</p>
</details>

User-Agent Shadow DOM & Rendering Mechanics

Internally, browser engines (Blink, Gecko, WebKit) implement <details> using an internal User-Agent Shadow DOM. When <details> does not have the open attribute, the rendering engine applies an internal display: none (or content-visibility style) to the content slot containing the non-summary child nodes.

<details> (User-Agent Shadow Tree)
  ├── <slot name="user-agent-custom-summary"> (Renders <summary> with disclosure triangle)
  └── <div class="details-content"> (Renders sibling children only when [open] is present)

In modern CSS standards (CSS Display Module Level 4), browsers expose the ::details-content pseudo-element, enabling direct styling of this internal container box without breaking semantic encapsulation.

The toggle Event Lifecycle

Whenever the user opens or closes a <details> element, the browser dispatches a native toggle event to the <details> element.

const detailsEl = document.querySelector('details');

detailsEl.addEventListener('toggle', (event) => {
  if (detailsEl.open) {
    console.log('Widget expanded — fetching telemetric payload...');
  } else {
    console.log('Widget collapsed.');
  }
});

Native <details> vs Custom <div> Disclosure Comparison

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 31–38: Defines the base styles for <details> and uses the details[open] attribute selector to dynamically change borders and background colors when expanded.
• Lines 58–65: Declares the semantic <details> element. Notice that no JavaScript is needed for the disclosure to function. Clicking <summary> toggles the visibility of .details-body.
• Line 59: The <summary> element acts as the primary interactive handle and keyboard anchor for the widget.
• Lines 73–84: Attaches an event listener for the native 'toggle' event. It evaluates disclosure.open (a boolean property reflecting the open content attribute) to update the status badge.

Expected Browser Render Output

1. Initial Closed State: A clean white card with a small right-facing triangle ▶ next to the text "View Provisioning Output (Worker Node #04)". The badge displays "Widget Status: Closed".
2. User Click or Spacebar Press: The triangle rotates downwards ▼, the background turns soft mint green (#f0fdf4), the dashed line and three log entries appear instantly, and the badge updates to "Widget Status: Open (Expanded)".