The summary Element

Technical Deep Dive & Specifications

The First-Child Requirement & Default Fallback

According to the WHATWG HTML Specification, if a <summary> element is present, it must be the very first element child of its parent <details> element.

<!-- Valid: <summary> is the first child -->
<details>
  <summary>System Specifications</summary>
  <p>Memory: 64GB DDR5</p>
</details>

<!-- Invalid Markup: Non-summary content appears before <summary> -->
<details>
  <p>Preamble text here...</p> <!-- Parser issue: Browser relocates or treats as content -->
  <summary>System Specifications</summary>
  <p>Memory: 64GB DDR5</p>
</details>

What Happens When <summary> is Omitted?

If a developer creates a <details> element without a <summary> child, the HTML specification mandates that the user agent must provide a default synthetic summary. In English-locale browsers, this synthetic summary displays the localized text "Details" alongside a default disclosure marker.

<!-- HTML authored without <summary> -->
<details>
  <p>This paragraph is hidden by default.</p>
</details>

<!-- User Agent renders a synthetic summary labeled "Details" -->

Keyboard Navigation & Accessibility Semantics

The <summary> element is natively interactive. It is mapped to the browser's Accessibility Tree with an implicit role="button" and an automatic aria-expanded state.

Customizing and Replacing the ::marker Indicator

By default, browsers render a disclosure triangle using the CSS list-style mechanism. The triangle is part of the ::marker pseudo-element.

                  +-----------------------------------+
                  |  summary { display: list-item; }  |
                  +-----------------------------------+
                                    |
                    +---------------+---------------+
                    |                               |
       Standard Modern CSS               Legacy WebKit Engine
   summary::marker { color: red; }   summary::-webkit-details-marker { display: none; }

Technique 1: Styling the Native Marker

summary::marker {
  color: #2563eb;
  font-size: 1.1em;
}

Technique 2: Removing the Marker Completely to Use Custom SVG Icons

To build custom accordion headers, developers remove the default marker across all browser engines using standard and legacy reset rules:

/* Remove default disclosure triangle across modern browsers and legacy Safari */
summary {
  list-style: none; /* Modern standard */
  display: flex;
  align-items: center;
  justify-content: space-between;
}

/* WebKit-specific legacy reset */
summary::-webkit-details-marker {
  display: none;
}

Semantic Headings Inside <summary>

When structuring FAQs, documentation manuals, or legal terms, each section title needs to appear in the document outline. Is it valid to put an <h3> inside a <summary>?

Yes. The WHATWG specification allows phrasing and heading content inside <summary>.

<!-- Correct Semantic Heading Integration -->
<details>
  <summary>
    <h3>Frequently Asked Questions: Billing & Invoicing</h3>
  </summary>
  <p>Invoices are generated on the 1st of every calendar month...</p>
</details>

[!IMPORTANT] Do NOT wrap <details> or <summary> inside a heading tag (e.g., <h3><summary>...</summary></h3> is invalid HTML). The heading tag must be placed inside the <summary> element.

The Nested Interactive Elements Anti-Pattern

According to HTML and ARIA specifications, interactive elements (such as <a>, <button>, <input>, or <select>) must never be nested inside <summary>.

<!-- ❌ CRITICAL ACCESSIBILITY ANTI-PATTERN -->
<summary>
  Terms of Service
  <a href="/legal.pdf" target="_blank">Download PDF</a> <!-- FORBIDDEN -->
  <button type="button">Print</button>                   <!-- FORBIDDEN -->
</summary>

Why this breaks:

1. Event Collision: Clicking the download link or button triggers both the link's action and the parent summary's toggle action.
2. Accessibility Failure: Assistive technologies (screen readers) announce the summary as a button. When a button contains an internal link or button, screen readers cannot properly convey the control hierarchy to blind users.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 24–36: Sets list-style: none on <summary> and display: none on summary::-webkit-details-marker to reliably strip the default browser disclosure marker across Chrome, Firefox, and Safari.
• Lines 26–28: Applies display: flex and justify-content: space-between to spread the text label and the custom SVG chevron to opposite edges of the container.
• Lines 37–40: Uses the :focus-visible pseudo-class to ensure keyboard users navigating with Tab receive an accessible focus ring without causing unsightly outlines on mouse clicks.
• Lines 50–54: Defines the CSS selector details[open] summary .chevron-icon to rotate the SVG icon 180 degrees smoothly when the parent details widget opens.
• Lines 65–72: Houses both the question text and the vector SVG inside the <summary> handle without introducing any illegal nested interactive elements.

Expected Browser Render Output

1. Initial State: A card displaying "What payment methods do you accept?" on the left, with a subtle gray downward chevron ⌵ on the far right. No default browser triangle is visible.
2. Keyboard Focus: Pressing Tab draws a crisp 2px blue focus outline around the summary row.
3. Activation: Pressing Space or clicking rotates the chevron smoothly upside-down ⌃, turns it blue, and displays the explanatory payment method paragraph below.