Skip to main content
Design system

Accordion

An accordion is a type of flexible container that allows the user to control the display of content by manually expanding and collapsing the container.

Bundle size: 4.2 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { Accordion } from "@washingtonpost/wpds-ui-kit"
|Copy

Anatomy

Note: Image is not to scale

  1. Header (text label)
  2. Panel (text or mixed content)
  3. Icon (state indicator e.g., Expanded, Collapsed)
  4. Divider
  5. Background color (set manually, default is "none")

Options

Density: Default

By default, accordion items are styled with a padding value that is appropriate for most use-cases.

Density: Compact

"Compact" density applies a minimal amout of padding to the accordion item, producing a slimmer footprint that takes up less visual space.

Density: Loose

"Loose" density applies a generous amount of padding to the accordion item, producing a larger footprint that occupies more visual space.


Behavior

Collapsed

Each accordion item consists of two main parts - the header, or item title and the panel, or item content. In the collapsed state, only the header is visible. When collapsed, the chevron icon also points down to provide a visual signal for revealing additional information. By default, all items in the accordion are displayed in the collapsed state unless otherwise specified.

Expanded

Users can access additional information by clicking or tapping the accordion item to reveal the expanded state. In the expanded state, the panel is displayed directly below the header. The chevron icon points up to indicate the current state and to provide a visual signal for returning the accordion item to its collapsed state.

Focus / Keyboard interaction

The accordion component is accessible via keyboard interaction. The "tab" key can be used to navigate items from top to bottom. The item currently in focus is denoted by a blue outline, using the CSS outline property. Pressing the "enter" ("return") key will expand or collapse the item in focus.

Disabled

The purpose of the accordion is to act as a container and visual interface for displaying static information upon user interaction. It is not intended to be used as an input element or form field. The accordion component does not require conditional logic to achieve its functionality and therefore does not feautre a special disabled state or possess any manner of error-handling. If visual feedback for a disabled state is desired, consider using the [.not-allowed] CSS property.


Guidance

Font family overrides

By default, the accordion component uses "Franklin Light" as its primary font for both the header and panel - however, font family overrides are premitted depending on the use-case. Below, the header has been set in "Postoni".

Font size overrides

The accordion component uses "size100" as its default font size. If a larger font size is desired, be mindful in choosing a size that is suitable for the use-case and appropriate for the space available. Avoid using font sizes that are excessively small or large, which may negatively affect your layout.

Don't split or truncate content

The header of the accordion should be a complete sentence or statement. It should not start in the header and continue in the panel.


API Reference

AccordionRoot

PropDescriptionTypeDefaultRequired
type
enum
single | multiple
----
True
valueThe controlled stateful value of the accordion item whose content is expanded. The controlled stateful value of the accordion items whose contents are expanded.
enum
string | string[]
----False
defaultValueThe value of the item whose content is expanded when the accordion is initially rendered. Use `defaultValue` if you do not need to control the state of an accordion. The value of the items whose contents are expanded when the accordion is initially rendered. Use `defaultValue` if you do not need to control the state of an accordion.
enum
string | string[]
----False
onValueChangeThe callback that fires when the state of the accordion changes.
enum
((value: string) => void) | ((value: string[]) => void)
----False
collapsibleWhether an accordion item can be collapsed after it has been opened.
enum
boolean
false False
disabledWhether or not an accordion is disabled from user interaction. @defaultValue false
enum
boolean & (boolean | true
----False
asChild
enum
boolean
----False

AccordionContent

PropDescriptionTypeDefaultRequired
asChild
enum
boolean
----False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False

AccordionItem

PropDescriptionTypeDefaultRequired
disabledWhether or not an accordion item is disabled from user interaction. @defaultValue false
enum
boolean
----False
valueA string value for the accordion item. All items within an accordion should use a unique value.
string
----
True
asChild
enum
boolean
----False

AccordionHeader

PropDescriptionTypeDefaultRequired
asChild
enum
boolean
----False

AccordionTrigger

PropDescriptionTypeDefaultRequired
asChild
enum
boolean
----False
density
enum
default | loose | compact
----False
forcefocus
enum
(boolean | true
----False