Expansion panel
A disclosure that shows or hides related content.
When to use
Use an expansion panel to disclose supporting content without leaving the page. A coordinated collection is an accordion; keep essential instructions visible without requiring disclosure.
Default
<div class="expansion-panel-container">
<div class="expansion-panel is-open">
<button
id="panel-header-1"
class="expansion-panel-header"
type="button"
aria-expanded="true"
aria-controls="panel-content-1">
Expansion Panel Header 1
</button>
<div
id="panel-content-1"
class="expansion-panel-content"
role="region"
aria-labelledby="panel-header-1">
<div class="expansion-panel-inner">Content</div>
</div>
</div>
<div class="expansion-panel">
<button
id="panel-header-2"
class="expansion-panel-header"
type="button"
aria-expanded="false"
aria-controls="panel-content-2">
Expansion Panel Header 2
</button>
<div
id="panel-content-2"
class="expansion-panel-content"
role="region"
aria-labelledby="panel-header-2"
hidden>
<div class="expansion-panel-inner">Content</div>
</div>
</div>
<div class="expansion-panel">
<button
id="panel-header-3"
class="expansion-panel-header"
type="button"
aria-expanded="false"
aria-controls="panel-content-3">
Expansion Panel Header 3
</button>
<div
id="panel-content-3"
class="expansion-panel-content"
role="region"
aria-labelledby="panel-header-3"
hidden>
<div class="expansion-panel-inner">Content</div>
</div>
</div>
</div>States
Each panel has its own trigger and region; a coordinated group is an accordion. Panels can be nested without inheriting a parent’s open state. Intrinsic-height animation supports dynamic content; reduced motion removes only the transition.
The preview starts with one panel open and the remaining panels collapsed. Update the trigger and content states together when opening or closing a panel.
Accessibility and behavior
- Use a native button for each trigger with
aria-expandedandaria-controls. Name the content region through the trigger’sidandaria-labelledby. - Enter or Space toggles the focused trigger. Synchronize
.is-open, the expanded state andhiddenso collapsed descendants cannot remain in keyboard navigation. - The Showcase provides toggle behavior, including nested panels. Consuming applications own this behavior; the package contains styles and respects reduced motion.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--expansion-panel-header-padding-y | var(--spacer-3) | Header top and bottom padding. | .expansion-panel |
--expansion-panel-header-padding-x | var(--spacer-3) | Header spacing at the inline start. | .expansion-panel |
--expansion-panel-header-icon-space | var(--spacer-5) | Header spacing reserved for the toggle icon at the inline end. | .expansion-panel |
--expansion-panel-inner-padding | var(--spacer-3) | Expanded content spacing. | .expansion-panel |
--expansion-panel-bg-color | var(--bg-surface) | Background color. | .expansion-panel |
--expansion-panel-header-bg-color | var(--bg-surface) | Header background. | .expansion-panel |
--expansion-panel-content-bg-color | var(--bg-surface) | Content panel background. | .expansion-panel |
--expansion-panel-header-hover-color | var(--action-color) | Header text color on hover. | .expansion-panel |
--expansion-panel-header-active-color | var(--action-color-active) | Header text color when pressed. | .expansion-panel |
--expansion-panel-border-width | var(--border-width) | Border thickness. | .expansion-panel |
--expansion-panel-border-color | var(--border-color) | Border color. | .expansion-panel |
--expansion-panel-border-radius | var(--border-radius) | Corner radius. | .expansion-panel |
--expansion-panel-icon-size | 2rem | Width and height of the toggle icon box. | .expansion-panel |
--expansion-panel-icon-inline-end | var(--spacer-2) | Toggle icon distance from the inline end. | .expansion-panel |
--expansion-panel-icon-closed | '+' | CSS content string for the collapsed indicator. | .expansion-panel |
--expansion-panel-icon-open | '−' | CSS content string for the expanded indicator. | .expansion-panel |
--expansion-panel-focus-outline-width | var(--focus-outline-width) | Focus ring thickness. | .expansion-panel (focus) |
--expansion-panel-focus-outline-style | var(--focus-outline-style) | Focus ring line style. | .expansion-panel (focus) |
--expansion-panel-focus-outline-color | var(--focus-outline-color) | Focus ring color. | .expansion-panel (focus) |
--expansion-panel-focus-outline-offset | var(--focus-offset) | Distance between the focus ring and control. | .expansion-panel (focus) |
--expansion-panel-transition-duration | var(--transition-duration) | Duration of visual state transitions. | .expansion-panel |
--expansion-panel-transition-easing | var(--transition-easing) | Timing curve for visual state transitions. | .expansion-panel |
--expansion-panel-content-transition-duration | var(--transition-duration) | Duration of content expansion and collapse. | .expansion-panel |