summary

The clickable heading for a details disclosure widget. Provides the visible label that toggles the expanded content.

Description

The <summary> element must be the first child of a <details> element. It acts as the disclosure button that users click or tap to expand or collapse the details content.

Browsers render <summary> with a disclosure triangle (marker) by default. Vanilla Breeze replaces this with a custom chevron indicator for better visual consistency.

When to Use

  • Inside details: Always pair with <details> as its first child
  • Descriptive labels: Provide clear, concise labels that describe what will be revealed
  • Question text: FAQ patterns with questions as summary content
  • Section headings: For collapsible content sections

Important

The <summary> element is only valid as the first child of a <details> element. Using it elsewhere has no special behavior or semantics.

Basic Example

Click this summary

The summary element acts as the trigger for the details content.

<details> <summary>Click this summary</summary> <p>The summary element acts as the trigger for the details content.</p> </details>

Customization

Text-Only Summary

Simple text summary

Most summaries contain just text, which is styled with medium font weight.

Summary with Inline Elements

You can include inline elements like icons, badges, or emphasis within the summary.

Important: Read this carefully

This content is marked as important using a strong element in the summary.

<details> <summary><strong>Important:</strong> Read this carefully</summary> <p>This content is marked as important.</p> </details>

Summary with Icons

Help and Information

Icons can provide visual cues about the content type.

Styling

The summary element receives careful styling to ensure touch-friendly sizing and clear visual feedback.

CSS Implementation

summary { padding: var(--size-s) var(--size-m); cursor: pointer; font-weight: 500; /* Hide default list marker */ list-style: none; /* Flexbox for alignment */ display: flex; align-items: center; justify-content: space-between; gap: var(--size-s); /* Touch-friendly minimum height */ min-block-size: var(--size-touch-min); /* 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); flex-shrink: 0; } /* Hide WebKit default marker */ &::-webkit-details-marker { display: none; } /* Focus state */ &:focus-visible { outline: var(--border-width-medium) solid var(--color-interactive); outline-offset: calc(var(--border-width-medium) * -1); } } /* Rotate chevron when open */ details[open] > summary::after { transform: rotate(45deg); }

Key Styling Features

Feature Implementation Purpose
Custom marker ::after pseudo-element Consistent chevron across browsers
Touch target min-block-size: var(--size-touch-min) 44px minimum for accessibility
Focus ring :focus-visible Keyboard navigation visibility
Animation transition on chevron Smooth open/close indicator

Layout Patterns

Default Layout

The summary uses flexbox with space-between to position the text and chevron.

Text on left, chevron on right

The default layout with justified content.

Multi-line Summary

Long summary text wraps naturally while the chevron remains aligned.

This is a longer summary text that will wrap to multiple lines on smaller screens

The chevron indicator stays aligned even with wrapping text.

Accessibility

Built-in Behavior

  • Acts as an implicit button - no role="button" needed
  • Keyboard accessible with Enter and Space keys
  • Screen readers announce expanded/collapsed state
  • Focus indicator provided via :focus-visible

Best Practices

  • Descriptive text: Write clear summaries that explain what content will be revealed
  • Avoid interactive children: Don't nest buttons, links, or other interactive elements inside summary
  • Single summary: Only one summary per details element
  • First child: Summary must be the first child of details

What to Avoid

<!-- Bad: Interactive element inside summary --> <details> <summary> Settings <button>Reset</button> <!-- Don't do this --> </summary> ... </details> <!-- Bad: Summary not first child --> <details> <p>Some text</p> <!-- Summary must come first --> <summary>Label</summary> ... </details>

Keyboard Support

Key Action
Tab Move focus to/from the summary element
Enter Toggle the details open/closed
Space Toggle the details open/closed

Screen Reader Announcements

When focused, screen readers will announce:

  • The summary text content
  • That it's a disclosure control (button)
  • Whether it's currently expanded or collapsed

Example announcement: "Click this summary, button, collapsed" or "Click this summary, button, expanded"

Related Elements

Browser Support

The <summary> element is supported in all modern browsers. The ::marker pseudo-element has varying support, which is why Vanilla Breeze uses ::after for the custom chevron indicator.