Accordion Open in Figma
The Accordion Component is a collapsible content container that allows users to show and hide sections of related content in a compact, organized manner. It enables content authors to present information in digestible chunks while maintaining a clean interface that doesn't overwhelm users with too much content at once.
pivot-accordion-default is a container web component that groups pivot-accordion-item elements. Multiple items can be open simultaneously. For card-styled items with single-open behavior, use pivot-accordion-elevated.
Quick Start
<pivot-accordion-default>
<pivot-accordion-item pivot-item-label="Section 1">
<p>Content for section 1</p>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Section 2">
<p>Content for section 2</p>
</pivot-accordion-item>
</pivot-accordion-default>Using the default slot
The default (unnamed) slot is the only slot pivot-accordion-default renders. It is designed to accept pivot-accordion-item elements as its slotted content:
<pivot-accordion-default>
<pivot-accordion-item pivot-item-label="Section 1">
<p>Content for section 1</p>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Section 2">
<p>Content for section 2</p>
</pivot-accordion-item>
</pivot-accordion-default>CSS Parts
| Name | Description |
|---|---|
container |
The outer wrapper div element |
Accessibility
pivot-accordion-default is an implicit grouping container and does not carry its own ARIA role — it renders a single unadorned <div part="container"> wrapping the slotted items. This matches the ARIA APG Accordion Pattern, which does not require a container role; the accessible name/role/value semantics (WCAG 4.1.2) are provided entirely by the pivot-accordion-item elements inside it.
Screen Reader Behavior
Screen readers encounter each accordion header button individually, in document order. The container itself is not announced and exposes no accessible name of its own.
Keyboard Navigation
pivot-accordion-default does not attach any keyboard handlers itself. Users navigate between accordion headers with Tab and Shift+Tab, or with arrow keys, Home, and End — all handled within pivot-accordion-item (see its README for the full key table). Because pivot-accordion-item’s arrow-key traversal queries its parent for sibling items, using pivot-accordion-default as the common parent is what makes that traversal work across the whole group (WCAG 2.1.1).
Focus Management
Focus is managed entirely within individual pivot-accordion-item elements (via delegatesFocus). pivot-accordion-default does not manipulate focus, set tabindex, or trap focus in any way.
Related Components
- Accordion Elevated — card-styled, single-open variant of this container.
- Accordion Item — the disclosure component
pivot-accordion-defaultcomposes; see its README for thepivot-accordion-item-toggleevent detail, per-item properties, and item-level accessibility behavior. - Accordion Stand Alone — use if only one accordion is needed.
References
- ARIA Authoring Practices Guide — Accordion Pattern
- Carbon Design System — Accordion Usage
- Carbon Design System — Accordion Accessibility
API Reference
Slots
| Name | Description |
|---|---|
default |
Default slot; accepts `pivot-accordion-item` elements |
Accordion
The Accordion Component is a collapsible content container that allows users to show and hide sections of related content in a compact, organized manner. It enables content authors to present information in digestible chunks while maintaining a clean interface that doesn’t overwhelm users with too much content at once.
Label
chevron-up
This default container can just accommodate standard text. If you need something more complex please swap this instance out with a custom one at the design level.
Usage
The accordion component serves as an effective way to organize and present content hierarchically, allowing users to focus on specific sections while keeping related information easily accessible.
Primary use cases
FAQs
When to use
- FAQ sections where users need to quickly scan questions and expand relevant answers
- Step-by-step processes that benefit from sequential revelation of information
- Content categorization when you have multiple related topics that don’t all need to be visible simultaneously
- Mobile-responsive layouts where screen real estate is limited and content needs to be condensed
- Information architecture that requires users to make choices about what content to consume
When not to use
- Critical information that users must see immediately without interaction
- Short content that would fit comfortably on the page without collapsing
- Comparison tasks where users need to view multiple sections simultaneously
- Linear reading experiences where content flows naturally from one section to the next
- Single items where there’s only one piece of collapsible content
Do’s and Don’ts
Follow these guidelines to ensure consistent, accessible, and user-friendly implementation of accordions.

✅ Do
Do use clear, descriptive headers that help users understand what content they’ll find when expanded

✅ Do
Do maintain consistent content structure across all accordion items for predictable user experience

✅ Do
Do consider mobile-first design since accordions work particularly well on smaller screens
Eligible Borrowers
chevron-up
Full-time
chevron-down
Part-time
chevron-down
This default container can just accommodate standard text.
❌ Don’t
Don’t create overly nested accordion structures that confuse users about their location
Information
chevron-up
Our offices will be closed on Monday, Oct. 13, in observance of the federal holiday.
❌ Don’t
Don’t use accordions for time-sensitive content that users need to access quickly
Important links
chevron-up
Pay your bill
Get help
❌ Don’t
Don’t hide essential navigation or critical calls-to-action within accordion panels
AEM Authoring Guidance
Search all the previous QA items sent to marketing team regarding this compoent and paste them here. This section might just be text and screenshots.
To implement this component:
- Instructions
- Instructions
- Instructions
Variants (styles in AEM - for authors)
This component includes the following variants for authors in AEM
Layout Options
- Standard Accordion
- Step Wizard with sequential step numbers next to each header
- White Background for an elevated appearance for expanded panels
Design Considerations
- Consideration 1
- Consideration 2
- Consideration 3
Design Specifications
- Header padding: primitives.$space-lg (default), primitives.$space-4xl (white background variant)
- Panel padding: primitives.$space-lg for mobile, primitives.$space-4xl for desktop white variant
- Step number circle: 50px diameter with 8px padding
Design Tokens Used
Name
Olivia Rhye
color.error
Olivia Rhye
Value
Olivia Rhye
#FF5C46
Olivia Rhye
Description
Olivia Rhye
Used for error, danger messages.
Olivia Rhye
Status & Changelog
This component is designed to support a wide range of user types, from end users interacting with an interface to internal users managing or configuring systems. It is commonly used by:
[check our pivot file for decisions documented there and check our decision log page. Add them chronologically, latest one on top]
Date
Olivia Rhye
2025-07-08
Olivia Rhye
Members
Olivia Rhye
Dave Karas
Olivia Rhye
Description
Olivia Rhye
Component map initialization and structural updates
Olivia Rhye
Default accordion (list type, multiple open)
Multiple items can be expanded simultaneously. No pivot-surface attribute set.
<pivot-accordion-default>
<pivot-accordion-item pivot-item-label="Section 1">
<pivot-text>Lorem ipsum dolor sit amet...</pivot-text>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Section 2">
<pivot-text>Content for section 2.</pivot-text>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Section 3">
<pivot-text>Content for section 3.</pivot-text>
</pivot-accordion-item>
</pivot-accordion-default>Default accordion with pivot-open
The second item starts expanded via the pivot-open attribute.
<pivot-accordion-default>
<pivot-accordion-item pivot-item-label="Section 1">
<pivot-text>Content for section 1.</pivot-text>
</pivot-accordion-item>
<pivot-accordion-item
pivot-item-label="Section 2 (expanded by default)"
pivot-open
>
<pivot-text>This item is already expanded on page load.</pivot-text>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Section 3">
<pivot-text>Content for section 3.</pivot-text>
</pivot-accordion-item>
</pivot-accordion-default>Rich slotted content
Accordion items accept any content in the default slot.
<pivot-accordion-default>
<pivot-accordion-item pivot-item-label="Item with rich content" pivot-open>
<pivot-text>Lorem ipsum dolor sit amet,...</pivot-text>
<pivot-spacer pivot-height="24"></pivot-spacer>
<pivot-button pivot-variant="secondary">Learn more</pivot-button>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Item with a link">
<pivot-text>
Visit
<pivot-link
pivot-inline
pivot-href="https://example.com"
pivot-target="_blank"
>example.com</pivot-link
>
for more information.
</pivot-text>
</pivot-accordion-item>
</pivot-accordion-default>