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

Content
HTML
<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-expanded and aria-controls. Name the content region through the trigger’s id and aria-labelledby.
  • Enter or Space toggles the focused trigger. Synchronize .is-open, the expanded state and hidden so 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.

TokenDefaultPurposeScope / state
--expansion-panel-header-padding-yvar(--spacer-3)Header top and bottom padding..expansion-panel
--expansion-panel-header-padding-xvar(--spacer-3)Header spacing at the inline start..expansion-panel
--expansion-panel-header-icon-spacevar(--spacer-5)Header spacing reserved for the toggle icon at the inline end..expansion-panel
--expansion-panel-inner-paddingvar(--spacer-3)Expanded content spacing..expansion-panel
--expansion-panel-bg-colorvar(--bg-surface)Background color..expansion-panel
--expansion-panel-header-bg-colorvar(--bg-surface)Header background..expansion-panel
--expansion-panel-content-bg-colorvar(--bg-surface)Content panel background..expansion-panel
--expansion-panel-header-hover-colorvar(--action-color)Header text color on hover..expansion-panel
--expansion-panel-header-active-colorvar(--action-color-active)Header text color when pressed..expansion-panel
--expansion-panel-border-widthvar(--border-width)Border thickness..expansion-panel
--expansion-panel-border-colorvar(--border-color)Border color..expansion-panel
--expansion-panel-border-radiusvar(--border-radius)Corner radius..expansion-panel
--expansion-panel-icon-size2remWidth and height of the toggle icon box..expansion-panel
--expansion-panel-icon-inline-endvar(--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-widthvar(--focus-outline-width)Focus ring thickness..expansion-panel (focus)
--expansion-panel-focus-outline-stylevar(--focus-outline-style)Focus ring line style..expansion-panel (focus)
--expansion-panel-focus-outline-colorvar(--focus-outline-color)Focus ring color..expansion-panel (focus)
--expansion-panel-focus-outline-offsetvar(--focus-offset)Distance between the focus ring and control..expansion-panel (focus)
--expansion-panel-transition-durationvar(--transition-duration)Duration of visual state transitions..expansion-panel
--expansion-panel-transition-easingvar(--transition-easing)Timing curve for visual state transitions..expansion-panel
--expansion-panel-content-transition-durationvar(--transition-duration)Duration of content expansion and collapse..expansion-panel