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';

type

defaultValue

none

isCollapsible

isDisabled

<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

Name	Type	Default	Required	Description
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.types.ts

Accordion.Header Props

Name	Type	Default	Required	Description
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	"function" | "article" | "code" | "details" | "html" | "iframe" | "input" | "label" | "link" | "map" | "menu" | "output" | "search" | "script" | "select" | "style" | "table" | "title" | ... 3567 more ... | { ...; }	-	-	The IconSymbol to display in the item header

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

AccordionHeader.types.ts

Accordion.Content Props

Name	Type	Default	Required	Description
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:

AccordionContent.types.ts

Accordion.Item Props

Name	Type	Default	Required	Description
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:

AccordionItem.types.ts

Accordion Classes

Class Name	Description
.abyss-accordion-root	Root element
.abyss-accordion-heading	Heading element for entire accordion
.abyss-accordion-heading-container	Heading container for entire accordion

Accordion.Header Classes

Class Name	Description
.abyss-accordion-header	Header element
.abyss-accordion-header-trigger	Header trigger element
.abyss-accordion-chevron-icon	Header chevron icon
.abyss-accordion-content-icon	Header content icon

Accordion.Content Classes

Class Name	Description
.abyss-accordion-content-container	Content container element
.abyss-accordion-content-wrapper	Content wrapper element
.abyss-accordion-content-subheading	Content subheading element
.abyss-accordion-content-text	Content text element

Accordion.Item Classes

Class Name	Description
.abyss-accordion-item	Item 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

Key	Description
Tab	Moves focus to the next focusable element; all focusable elements in the accordion are included in the page Tab sequence.
Shift + Tab	Moves focus to the previous focusable element; all focusable elements in the accordion are included in the page Tab sequence.
Enter or Space	When focus is on the accordion header for a collapsed or expanded panel, pressing Enter or Space will expand or collapse the panel, respectively.
Arrow Down	If 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 Up	If 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.
Home	Moves focus to first accordion header.
End	Moves focus to last accordion header.

Component Tokens

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

Search tokens

Accordion Tokens

Token Name	Value
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