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 by default. Vanilla Breeze replaces this with a custom chevron indicator that rotates on open, and ensures a touch-friendly 44px minimum height.
When to Use
- Inside details: Always pair with
<details>as its first child - Descriptive labels: Clear, concise text that describes what will be revealed
- Question text: FAQ patterns with questions as summary content
- Section headings: 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.
Variants
Summary supports plain text, inline elements (bold, emphasis, code), and icons. Long text wraps naturally while the chevron remains aligned.
<details> <summary>Click this summary</summary> <p>The summary element acts as the trigger for the details content.</p></details><details> <summary><strong>Important:</strong> Read this carefully</summary> <p>Inline elements work naturally inside summary.</p></details><details> <summary> <span style="display: flex; align-items: center; gap: var(--size-xs);"> <icon-wc name="info" size="s"></icon-wc> Help and Information </span> </summary> <p>Icons provide visual cues about the content type.</p></details>CSS Reference
The summary element receives careful styling to ensure touch-friendly sizing, consistent chevron indicators, and clear keyboard focus.
summary { padding: var(--size-s) var(--size-m); cursor: pointer; font-weight: 500; list-style: none; display: flex; align-items: center; justify-content: space-between; gap: var(--size-s); /* Touch-friendly minimum height (44px) */ 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; } &::-webkit-details-marker { display: none; } &: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 transform |
Smooth chevron rotation on open/close |
| Marker hiding | list-style: none + ::-webkit-details-marker |
Cross-browser removal of native triangle |
Context-Specific Overrides
Summary styling changes in different parent contexts:
| Context | Indicator | Other Changes |
|---|---|---|
nav.tree |
+/− text indicator via ::before |
Smaller padding, no border. Hover highlights. |
accordion-wc |
Base chevron (inherited) | ARIA aria-controls added. Keyboard arrow navigation between summaries. |
tab-set |
Chevron hidden (::after { display: none }) |
Summary becomes tab button. Active tab gets blue bottom border. |
@media print |
Hidden | Chevron and marker removed for clean printing. |
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>Screen Reader Announcements
When focused, screen readers announce the summary text, that it's a disclosure control (button), and whether it is expanded or collapsed. Example: "Click this summary, button, collapsed"
Keyboard Support
| Key | Action |
|---|---|
| Tab | Move focus to/from the summary element |
| Enter | Toggle the details open/closed |
| Space | Toggle the details open/closed |
Related
<details>— The parent disclosure widget (required)<accordion-wc>— Enhanced accordion with keyboard navigation between panels<tab-set>— Tab interface where summary becomes the tab button<nav>— Tree navigation uses summary as collapsible section headers<dialog>— For modal overlays rather than inline disclosure
Browser Support
The <summary> element is supported in all modern browsers. The ::marker pseudo-element has varying support for customization, which is why Vanilla Breeze uses ::after for the chevron indicator.