Skip to main content

Accordion

A vertically stacked list of headers that reveal or hide associated sections of content.

Submit feedback
Edit this page
github
View source code
figma
View design

Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.
Component Guide
import { Accordion } from '@uhg-abyss/web/ui/Accordion';
<Accordion>
  <Accordion.Item value="sandbox-1">
    <Accordion.Header>Sandbox Accordion 1</Accordion.Header>
    <Accordion.Content>
      SURPRISE - Sandbox Accordion 1
    </Accordion.Content>
  </Accordion.Item>


  <Accordion.Item value="sandbox-2">
    <Accordion.Header>Sandbox Accordion 2</Accordion.Header>
    <Accordion.Content>
      SURPRISE - Sandbox Accordion 2
    </Accordion.Content>
  </Accordion.Item>


  <Accordion.Item value="sandbox-3">
    <Accordion.Header>Sandbox Accordion 3</Accordion.Header>
    <Accordion.Content>
      SURPRISE - Sandbox Accordion 3
    </Accordion.Content>
  </Accordion.Item>
</Accordion>

Definitions​

(The terms in parentheses are the official names used by the WAI-ARIA)

Accordion heading​

On Accordion use the heading prop to set a heading for the entire accordion component. Use the headingLevel prop to set the heading level. The default is set to 2 which renders the heading element as an <h2>.

It also holds the optional "Expand all / Collapse all" button, which is further defined in the section Controlled expanded state.

Accordion header​

  • Label or thumbnail representing a section of content that also serves as a control for showing and, in some implementations, hiding the section of content.

  • Use the headingLevel prop available on Accordion.Header to set the heading level of the accordion item. The default is set to 3 which renders the heading element as an <h3>.

  • Use the icon prop to add an IconSymbol to the header. icon accepts a string (the name of the IconSymbol to use) or an object of the following type:

    {
      icon: string;
      variant: 'filled' | 'outlined';
    }

Nesting heading level correctly​

Whether the first heading of the Accordion is the main (group) heading or accordion header, make sure the component nests correctly in your main content. The <h2> default for the (group) heading assumes it is a "top" level item that is one level below the primary <h1> heading. The accordion headings default to <h3> since it's assumed it will be part of a content section starting with <h2> which can be the main content without a group heading.

If these assumptions do not apply to where Accordion is nested in main page content, be sure to adjust the headingLevel prop to nest the (group) heading - if used - or the accordion header (if heading is not included).

Accordion content (accordion panel)​

Section of content associated with an accordion header.

Use prop subheading on Accordion.Content to add a subheading to the content area.

Type and default value​

Use the type property to control whether the accordion can have one or multiple items open at a time. The possible values are 'single' and 'multiple'. The default is set to 'single'.

Use the defaultValue property to set which item or items are open by default. The value of defaultValue depends on the value of type.

Single​

When type is set to 'single', defaultValue accepts a string.

Multiple​

When type is set to 'multiple', defaultValue accepts an array of strings.

Collapsible​

The isCollapsible property allows closing content when clicking the trigger for an open item when type is 'single'. When true, all items can be collapsed. When false, one item will always remain open. The default is set to false.

Note: When type is 'multiple', isCollapsible does not apply and is undefined.

Trigger position​

Use the triggerPosition prop on Accordion to set the position of the trigger to the left or right of the accordion header. The default value is 'right'.

Disabled​

Use the isDisabled property to disable the entire Accordion or individual items. The default is set to false.

onValueChange​

The onValueChange property is an event handler that is called when the expanded state of any item changes.

Controlled expanded state​

Expand all button​

When the accordion has type 'multiple' and the expandValues prop is provided, an "Expand all / Collapse all" button will appear in the accordion heading.

expandValues accepts an array of strings that correspond to the value of each Accordion.Item that should be expanded or collapsed when "Expand all / Collapse all" is clicked. For the optimal user experience, it is recommended you provide the values for all accordion items.

Custom controlled expanded state​

You can additionally control the expanded state of the accordion by using the value prop in combination with onValueChange. This allows you to programmatically control which items are expanded.

Accordion Props

NameTypeDefaultRequiredDescription
children
React.ReactNode
--
The Accordion items; must be Accordion.Item components
className
string
--
CSS class name to apply to each element within the component
css
Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>
--
Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
See CSS Prop Styling for more information
data-testid
string
--
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
defaultValue
string | string[]
--
The default Accordion item to be expanded on load
The default Accordion item(s) to be expanded on load
disableDefaultProviderProps
boolean
false
-
If set to true, the component will not use the DefaultPropsProvider values.

If you aren’t using the DefaultPropsProvider, this prop can be ignored.
expandValues
string[]
--
If defined, a button to expand/collapse all items in the array will be rendered when type is 'multiple'
heading
React.ReactNode
--
The heading for the entire Accordion, rendered above all items
headingLevel
1 | 2 | 3 | 4 | 5 | 6
2
-
Heading level for the accordion heading (affects all child heading levels)
isCollapsible
boolean | undefined
false
-
If true, the Accordion will be collapsible
isCollapsible should be undefined when type is 'multiple'
isDisabled
boolean
false
-
If true, the Accordion will be disabled
onValueChange
(value: string) => void | (value: string[]) => void
--
Callback function executed when the expanded state of an item changes
triggerPosition
"left" | "right"
'right'
-
Position of the trigger icon
type
"single" | "multiple"
'single'
-
The type of Accordion: 'single'
The type of Accordion: 'multiple'
value
string | string[]
--
The controlled stateful value of the expanded Accordion item
The controlled stateful value of the expanded Accordion item(s)

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Accordion.Header Props

NameTypeDefaultRequiredDescription
children
React.ReactNode
-
The content of the Accordion header
className
string
--
CSS class name to apply to each element within the component
css
Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>
--
Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
See CSS Prop Styling for more information
data-testid
string
--
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
disableDefaultProviderProps
boolean
false
-
If set to true, the component will not use the DefaultPropsProvider values.

If you aren’t using the DefaultPropsProvider, this prop can be ignored.
headerElement
string
'undefined (uses heading based on headingLevel)'
-
The element type to render as the header wrapper. When specified, overrides the default heading element.
headingLevel
1 | 2 | 3 | 4 | 5 | 6
3
-
Heading level of the Accordion header
icon
string | { icon: string; variant: "filled" | "outlined" | undefined; }
--
The IconSymbol to display in the item header

Below are the link(s) to the relevant GitHub type files:

Accordion.Content Props

NameTypeDefaultRequiredDescription
children
React.ReactNode
-
The body of the Accordion content
className
string
--
CSS class name to apply to each element within the component
css
Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>
--
Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
See CSS Prop Styling for more information
data-testid
string
--
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
disableDefaultProviderProps
boolean
false
-
If set to true, the component will not use the DefaultPropsProvider values.

If you aren’t using the DefaultPropsProvider, this prop can be ignored.
subheading
React.ReactNode
--
The subheading in the Accordion content

Below are the link(s) to the relevant GitHub type files:

Accordion.Item Props

NameTypeDefaultRequiredDescription
children
React.ReactNode
--
The content of the Accordion item
className
string
--
CSS class name to apply to each element within the component
css
Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>
--
Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
See CSS Prop Styling for more information
data-testid
string
--
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
disableDefaultProviderProps
boolean
false
-
If set to true, the component will not use the DefaultPropsProvider values.

If you aren’t using the DefaultPropsProvider, this prop can be ignored.
isDisabled
boolean
false
-
If true, the Accordion item will be disabled
value
string
-
Unique identifier for the Accordion item

Below are the link(s) to the relevant GitHub type files:

Accordion Classes

Class NameDescription
.abyss-accordion-rootRoot element
.abyss-accordion-headingHeading element for entire accordion
.abyss-accordion-heading-containerHeading container for entire accordion

Accordion.Header Classes

Class NameDescription
.abyss-accordion-headerHeader element
.abyss-accordion-header-triggerHeader trigger element
.abyss-accordion-chevron-iconHeader chevron icon
.abyss-accordion-content-iconHeader content icon

Accordion.Content Classes

Class NameDescription
.abyss-accordion-content-containerContent container element
.abyss-accordion-content-wrapperContent wrapper element
.abyss-accordion-content-subheadingContent subheading element
.abyss-accordion-content-textContent text element

Accordion.Item Classes

Class NameDescription
.abyss-accordion-itemItem element

An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content. The headings function as controls that enable users to reveal or hide their associated sections of content. Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page.

Adheres to the Accordion WAI-ARIA design pattern.

Accordion WAI-ARIA Example

Reduced Motion

For users who have prefers-reduced-motion set to reduced, the animation of the spinning caret and expand/collapse is disabled.

Keyboard Interactions

KeyDescription
TabMoves focus to the next focusable element; all focusable elements in the accordion are included in the page Tab sequence.
Shift + TabMoves focus to the previous focusable element; all focusable elements in the accordion are included in the page Tab sequence.
Enter or SpaceWhen focus is on the accordion header for a collapsed or expanded panel, pressing Enter or Space will expand or collapse the panel, respectively.
Arrow DownIf focus is on an accordion header, moves focus to the next accordion header. If focus is on the last accordion header, either does nothing or moves focus to the first accordion header.
Arrow UpIf focus is on an accordion header, moves focus to the previous accordion header. If focus is on the first accordion header, it either does nothing or moves focus to the last accordion header.
HomeMoves focus to first accordion header.
EndMoves focus to last accordion header.

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Accordion Tokens

Token NameValue
accordion.color.border.bottom.container
#CBCCCD
accordion.color.border.separator
#CBCCCD
accordion.color.icon.content.disabled
#7D7F81
accordion.color.icon.content.enabled
#002677
accordion.color.icon.utility.disabled
#7D7F81
accordion.color.icon.utility.enabled
#002677
accordion.color.surface.content
#FFFFFF
accordion.color.surface.header.default.active
#E5E5E6
accordion.color.surface.header.default.hover
#F3F3F3
accordion.color.surface.header.default.rest
#FFFFFF
accordion.color.surface.header.disabled
#F3F3F3
accordion.color.surface.header.selected.active
#D9E9FA
accordion.color.surface.header.selected.hover
#E3EEFA
accordion.color.surface.header.selected.rest
#EDF3FB
accordion.color.text.heading.disabled
#7D7F81
accordion.color.text.heading.enabled
#002677
accordion.color.text.heading.accordion-group
#002677
accordion.color.text.paragraph
#4B4D4F
accordion.color.text.sub-heading
#323334
accordion.border-width.bottom.container
1px
accordion.sizing.all.icon.utility
24px
accordion.sizing.all.icon.content
24px
accordion.spacing.gap.vertical.content
4px
accordion.spacing.gap.vertical.heading
8px
accordion.spacing.gap.horizontal.header
8px
accordion.spacing.padding.all.header
16px
accordion.spacing.padding.left.content.expand-left
48px
accordion.spacing.padding.left.content.expand-right
16px
accordion.spacing.padding.right.content
16px
accordion.spacing.padding.horizontal.heading.web
16px
accordion.spacing.padding.horizontal.heading.mobile
8px
accordion.spacing.padding.vertical.content
16px
accordion.spacing.padding.vertical.heading
16px
accordion.spacing.padding.vertical.expand-button
4px
Table of Contents