Disclosures

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
StyleUse whenWhy
BorderedGrouping self-contained settings, help, or supporting information.The surrounding border connects the header and body.
FilledShowing 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.

Theme comparison: These source examples force light and dark schemes. The compiled package follows system preference; see the generated-package example and theme guidance.

Disclosure animation

Compare the library’s smooth opening and closing with an instant response in the examples below.

Panels stay instant when your browser does not support this animation or you prefer reduced motion. Try both styles, long filter selections, narrow panels, and a quick second toggle while a panel is moving.

No selections · collapsed

Light mode

Dark mode

No selections · expanded

Light mode

Dark mode

Selected filters · collapsed

Light mode

Dark mode

Selected filters · expanded

Light mode

Dark mode

Many selections · collapsed

Light mode

Dark mode

Many selections · expanded

Light mode

Dark mode

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

Bordered sections · matching chevrons

Collapsed

Light mode

Shopping preferences Choose how completed items are displayed and how your shopping list is organized.

This bordered section uses the same inward/downward chevron and keeps it aligned with the title.

Dark mode

Shopping preferences Choose how completed items are displayed and how your shopping list is organized.

This bordered section uses the same inward/downward chevron and keeps it aligned with the title.

Expanded

Light mode

Shopping preferences Choose how completed items are displayed and how your shopping list is organized.

This bordered section uses the same inward/downward chevron and keeps it aligned with the title.

Dark mode

Shopping preferences Choose how completed items are displayed and how your shopping list is organized.

This bordered section uses the same inward/downward chevron and keeps it aligned with the title.

Composition and accessibility

  • Show “All items” when neither group is restricted. Otherwise, join selected labels with middle dots in stable group order. The whole summary may wrap beneath the title; keep Clear and the chevron on its first line. Do not add category prefixes when the labels already explain themselves.
  • Clear is a named native button outside summary in the DOM, visually positioned in a reserved header slot. Its target must not cover the title or chevron. It clears both groups, returns focus to summary before hiding, and leaves expansion unchanged. In the keyboard order, it follows the visible filter controls when expanded and follows summary directly when collapsed.
  • “All stores” and “All categories” reset only their own group. Native buttons use aria-pressed; closing preserves selections. Native summary exposes expansion without a duplicate role or ARIA state. See MDN summary guidance.
  • These controls add no live announcement duplicating pressed-state feedback. Applications own actual filtering, persistence, and concise result messages. Keep a result region mounted before updates; follow the catalog's live-region timing and naming guidance.
  • specimen-filter-* and specimen-disclosure-* are example-only layout classes. disclosure-filters.js supplies one shared synthetic renderer/controller for the working example and state gallery. Neither the layout hooks nor scripts are public library APIs or shipped package code.
  • Verify target separation, native keyboard behavior, focus after clearing, long and translated labels, narrow layouts, real zoom, and actual screen-reader speech in your application. Browser assertions do not establish spoken output or physical-device behavior.

Working catalog example and application responsibilities · Package API and customization reference