Bordered and filled panels, working filters, animation, and state comparisons.
Disclosures
Accessibility: Keep native details/summary semantics; avoid redundant roles, tabindex and aria-expanded. Required instructions must remain visible. MDN summary guidance.
Use details.disclosure to group optional settings, filters, or supporting information. Both variants use the same native disclosure markup and a full-width summary target. Keep essential instructions visible outside collapsed sections.
Place the label in disclosure-label, its title in disclosure-title, optional supporting text in disclosure-description, and the body in disclosure-content. A heading can carry both label and title classes. Choose its level for the page hierarchy; the class only normalizes its appearance.
These examples use native disclosure behavior: Enter or Space opens a focused summary, and multiple sections can stay open. Checkboxes and Reset work locally without saving. Put links and inputs in the body. Extra header actions must be siblings outside the summary with separate targets, as in the filled filter example below. Nest only when the content needs that hierarchy.
Choose a disclosure style| Style | Use when | Why |
|---|
| Bordered | Grouping self-contained settings, help, or supporting information. | The surrounding border connects the header and body. |
|---|
| Filled | Showing filters or compact controls whose current state matters while collapsed. | The filled header emphasizes the summary; the accent border connects expanded content. |
|---|
Both styles animate opening and closing when the browser supports the required CSS and reduced motion is not requested. Otherwise, panels open and close instantly. Closed content remains searchable after the closing transition. Compare animated and instant behavior.
These are recommendations, not restrictions. Both styles support the same content and native behavior. Chevrons point inward when collapsed and down when expanded, aligned with the title’s first line. Compare all disclosure states.
Bordered disclosure
Use .disclosure for an enclosing border, trailing chevron, and divider when open.
Bordered · light
Preferences
Choose which local hints to show. Closing this section preserves your choices; Reset restores this example’s defaults.
Shopping filtersAll stores · All categories
The supporting summary describes the current selection. An application updates it when its filters change.
Each section opens independently. The library does not save expansion state or require other sections to close.
How matching works
An item matches any selected store and any selected category. Both groups apply together.
See the chip examples for selectable filters.
Help with shopping preferences and shared lists across multiple devices
Long labels wrap while the chevron stays reachable. Allow room for translated text and increased text size.
Bordered · dark
Preferences
Choose which local hints to show. Closing this section preserves your choices; Reset restores this example’s defaults.
Shopping filtersAll stores · All categories
The supporting summary describes the current selection. An application updates it when its filters change.
Each section opens independently. The library does not save expansion state or require other sections to close.
How matching works
An item matches any selected store and any selected category. Both groups apply together.
See the chip examples for selectable filters.
Help with shopping preferences and shared lists across multiple devices
Long labels wrap while the chevron stays reachable. Allow room for translated text and increased text size.
The summary target is at least 2.75rem high (44px at a 16px root size). Keyboard focus uses the library’s separate outline; hover and press tint the summary. The same panel treatment applies in both themes.
Use the native open attribute for an initially expanded section. Leave off the native name attribute to allow independent expansion. Do not add a button role, tabindex, or manually maintained aria-expanded to the summary. Applications own persistence and control behavior; no JavaScript is needed for opening and closing. If heading navigation inside a summary matters, check it with your target assistive technology, or place a section heading outside the disclosure. See summary heading guidance.
Unclassed details keeps the browser’s native appearance. App layouts own spacing between panels; the examples use a grid gap. Customize through the existing color, spacing, and radius tokens or scoped application CSS.
<details class="disclosure">
<summary>
<span class="disclosure-label disclosure-title">Preferences</span>
</summary>
<div class="disclosure-content">
<p>Settings and controls go here.</p>
</div>
</details>
Filled disclosure · working filters
Add .disclosure--filled to details.disclosure for a filled header, shared chevron, and accent-colored body border with a gap below the header. Use a persistent summary when selections matter even while the controls are collapsed.
Try selecting aldis and costco, then black and blue, and collapse Filters. “All stores” and “All categories” clear their own group; the X clears both. Each theme has independent, synthetic state. Nothing is saved or sent.
Filled · light
Filled · dark
Application responsibilities: Keep the visible summary current in both states: show “All items” when neither group is restricted, otherwise join selected labels with middle dots in stable group order. Native aria-pressed buttons expose each selection; this example adds no duplicate live announcement. If filtering changes a results list, follow the result-status guidance for a persistent live region and concise counts.
Clear action: The X is a named button outside summary in the DOM, positioned inside the filled header before the chevron. Reserve its target space so it cannot cover the title or chevron. Clear and the chevron stay beside the first title line while the selected labels wrap together below it. Clear must not toggle expansion; focus summary before hiding the X. When expanded, keyboard navigation reaches Clear after the body controls; when collapsed, directly after summary. Empty groups select their “All” action. Applications own filtering, persistence, result announcements, and focus transitions.
Example-only code: The specimen-filter-* classes provide inline/wrapping summary text, field-group spacing, and sibling clear-action placement. They are not library APIs. disclosure-filters.js shares local selection/reset behavior with the state gallery; the CSS package contains no JavaScript. Reuse the public disclosure and chip hooks, then implement your application's layout and state.
<details class="disclosure disclosure--filled" open>
<summary>
<span class="disclosure-label">
<span class="disclosure-title">Filters</span>
<span class="disclosure-description">All items</span>
</span>
</summary>
<div class="disclosure-content">
<!-- Filter controls belong here. -->
</div>
</details>
Full state gallery: no selections, short selections, and many selections, each collapsed and expanded, in both themes. The gallery includes reset, narrow panels, and bordered examples. The working controls are generated by example-only JavaScript; the markup and library styling remain reusable separately.
This minimal snippet stacks the description below the title. The working example adds application layout for the inline summary and clear button. The shared accessibility guidance above applies to both variants.
Use the bordered style for self-contained settings and help, or the filled style for compact controls with a useful collapsed summary. Both use native details/summary. Markup and choosing a style.
These six filter states cover no selections, short selections, and wrapped selections, each collapsed and expanded. Clear stays inside the filled header before the chevron, aligned with the title. Examples are independent, synthetic, and never saved or sent.
Filled disclosure · content to the edge
The shaded shopping-list rows reach the same right edge as the header. The accent border and left inset stay in place; each row supplies its own text padding.
Light mode
Shopping list
Three essentials for the week
- Apples · 6 loose
- Rolled oats · 1 large bag
- Whole-grain bread · 1 loaf for the freezer
Dark mode
Shopping list
Three essentials for the week
- Apples · 6 loose
- Rolled oats · 1 large bag
- Whole-grain bread · 1 loaf for the freezer