Accordion

ECT approvedUpdated May 21, 2026

Description

An accordion is used to group, hide, and reveal content using progressive disclosure.
When closed, an accordion shows top-level information only.
A user can open the accordion and quickly access more information.

Warning

Choose the right component Other components that can be used for progressive disclosure include: checkbox component radio button component link component

Component preview

Information

Loading Carbon component...

Open in Storybook

No live controls configured for this component.

Anatomy

Anatomy

Types

Standard

Simple

Size

The accordion height adjusts to the content in the heading and content areas.
The default accordion width is 100 percent of the accordion's parent container.
Standard accordion is available in S size and M size.
Simple accordion is available in S size, M size and L size.

States

Warning

States are visual indicators used to communicate a component’s interaction status. Learn more about commonly used component states in our General specs

Component-specific states

Closed

Open

Color mode

Light

Dark

Variations

Grouped

Subtitle

Detailed icon

No padding

Examples

Accordions can be embedded into containers like Tile, Card, and Sidebar.
Top and bottom dividers can be removed if needed to fit better with the design of the parent container.

Tile

Card

Sidebar

Best practices

Use accordions sparingly.
Having too much content in an accordion makes it hard to find information.
Having too many accordions on a page makes it hard to navigate the page.
Keep accordions open or closed until a user interacts with them. Consider whether 1 or more accordion sections can be open at the same time.
When the accordion content is longer than the viewport, display a vertical scrollbar for the whole accordion.
Never allow content to scroll vertically on individual content panels.
Never allow content to scroll horizontally on the whole accordion or individual content panels.
Avoid putting important controls (for example, a primary button) in an accordion.
Avoid putting accordions within accordions.
Make the title short, clear, and descriptive.
Use paragraphs and subheadings for content if necessary.

Dos and don'ts

Technical example

Accordion component implemented in Carbon.

Title

Be as concise as possible, yet clear and specific enough that users should be able to understand the purpose before reading the content.
If the title gets too long, you can move some details to the subtitle.

Content

Having too much content in an accordion makes it hard to find information.
Use paragraphs and subheadings if necessary.

Overview and triggers

Accordions are very interactive. They have a wide variety of motions that can be applied to them.

These motions are triggered either by a user hovering over or pressing a title, or by tapping a chevron.

Motion is applied to the following elements:

Motion Applied to	Resulting Change	Description
Chevron	Rotation	The chevron’s direction is down for ‘inactive’ or left for ‘active’
Textbox & Shadow	Opacity (solid versions)	The textbox is hidden when ‘inactive’ or visible when ‘active’
Accordion Titles	PositionPositionColor	The title can move upwards or downwards as sections open and closeThe title undergoes a lazy load when it loadsThe title’s color changes from A to B when hovered over

Gestural considerations

Mobile / Tablet

A tap on chevron works in the same way as a click on desktop with timings and motion remaining the same. A press on the title will imitate a hover on desktop.

Technical details of Motion

Motion Applied to	Property	Details	Duration	Easing
Chevron	Rotation	Activated 0 to -180Deactivated -180 - 0	400ms (Fast)400ms (Fast)	Reveal In/OutReveal In/Out
Textbox & Shadow	Opacity (solid v)	Content Fades 0 to 100 or rev.	200ms (Fast)	Standard In/Out
Accordion Titles	Pos - YEach Pos YColor	Moved dependent on other states10% Vh / 100ms delay on eachVersion-dependent hover and active states will have different bg color	400ms (Fast)400ms (Fast)400ms (Fast)	Reveal In/OutReveal In/OutStandard In/Out

Requirements

Users should be able to:

Navigate to the accordion using a keyboard or other assistive technology.
Expand and collapse sections using the keyboard or other assistive technology.
Know whether the accordion is expanded or collapsed.
Understand the purpose of content sections through clear, descriptive labels.

Interactions

The accordion is closed by default. Do not close one accordion when another is opened. Let users open and close accordions themselves.

Keyboard interactions

Tab. Moves focus to the accordion header from the previous interactive element.
Pressing tab again moves focus to the next interactive element on the page.
Space or Enter. Expands or collapses the accordion panel.

Design considerations

Give accordions clear, descriptive content within the accordion button that describes the accordion panel content that follows them.
Use clear visual indicators for the expanded and collapsed states.
Left align visual indicators and place them near to the header so they are easier to see for users with low vision.

Development considerations

The accordion button must have an accessible name that matches the visible label.
The accordion header must be a element, or have role="button" with an aria-expandedattribute that can be toggled using JavaScript.
If the panel is expanded, use aria-expanded="true".
If the panel is collapsed, use aria-expanded="false".
The accordion header must have an aria-controls property set to the unique id of the panel it controls.

Date	Changes
August 2025	Renamed accordion types from Typical and Subtle to Standard and Simple in accordance with our latest naming conventions.Moved guidance from Variations to new Types section.
August 2025	Updated guidance on the accessibility tab.
September 2024	New version created. Previous versions archived in the frozen Web and Product design system.