Accordion

v1.0.0 | View in Storybook

​

When to use

• Settings and configuration (side) panels: Group related settings together and consider an Accordion to progressively disclose information so it does not overwhelm the user. Example: Grouping advanced configuration options in a side panel so users expand only the sections they need.
• Form design: Split long forms into collapsible sections to make them less intimidating.

Example: Breaking a long registration or onboarding form into collapsible steps such as “Profile,” “Permissions,” and “Review.”

• Documentation or help centers: Organize FAQs, how-tos, or feature details.

Example: Structuring an FAQ page where each question is an Accordion header and the answer appears when expanded.

• Content hierarchies: Show nested structures such as folders, files, or comments.

Example: Displaying a folder tree or nested comment thread where each level can be expanded or collapsed independently.

​

When to use something else

• All content must be visible at once. Consider a simple list, Data grid, Card, or another layout that shows information by default.
• Simple, short content or content users need to search or scan quickly. Consider typography and grouping instead of hiding sections.
• High-stakes decisions or multi-step workflows: If users must compare information or switch between sections repeatedly, hiding content may cause errors—keep relevant sections visible or use Tabs / Segmented control for switching.

​

Dos and don’ts

• Do ensure titles accurately represent the content within.
• Do maintain consistency in icon usage and styling.
• Don’t use for short, simple content.
• Don’t nest Accordions within each other.

​

Behavior

• Headers are the primary control: they expand or collapse the associated panel on activation (click, tap, Enter, or Space when focused).
• Unless the product specifies single-expand mode, opening one section does not have to close others; match the pattern used elsewhere in the app.
• Expanded content stays in the document and must be available to assistive technologies (no display: none on critical copy without an accessible alternative).

​

Often used with

Separator, headings, and form controls (Input, Select, Checkbox, etc.) inside panels; optional Button in group headers when specified by the pattern.

​

Accessibility

• ARIA and hierarchy: Wrap trigger buttons in appropriate heading levels (<h3>, <h4>) using AccordionHeader. Ensure aria-expanded and aria-controls are bound correctly.
• Keyboard navigation: Tab moves focus to triggers, Arrow Up / Arrow Down navigates between headers, and Space or Enter expands/collapses panels.
• Focus management: Maintain visible focus indicators on individual AccordionTrigger elements; do not lose focus state when collapsing an open panel.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Default expanded

Use this variant when one section should be open on first load—for example, the most common FAQ answer or the primary settings group—so users see important content without an extra click.

​

With icons

When any Accordion header uses a leading icon, give every header in that group an icon so labels stay aligned and the list remains easy to scan.

​

Multiple

Allow multiple Accordions to be expanded at the same time when users may need to view or edit content in more than one section at once or need to compare information.

​

Controlled

Use a controlled Accordion when expand and collapse state must follow application logic—for example, syncing with URL parameters, a parent form, or programmatic open and close.

​

Disabled

Use a disabled section when content is temporarily unavailable, and add a tooltip or helper text that explains why the section cannot be opened.