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: 189.55 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { Accordion } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github

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
"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.
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.
string | string[]
----False
onValueChangeThe callback that fires when the state of the accordion changes.
((value: string) => void) | ((value: string[]) => void)
----False
collapsibleWhether an accordion item can be collapsed after it has been opened.
boolean
false False
disabledWhether or not an accordion is disabled from user interaction. @defaultValue false
boolean & (boolean | "true" | ({ "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 18 more ...; "@initial"?: boolean | "true"; } & { ...; }))
----False
orientationThe layout in which the Accordion operates.
"horizontal" | "vertical"
vertical False
dirThe language read direction.
Direction
----False
asChild
boolean
----False

AccordionContent

PropDescriptionTypeDefaultRequired
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False

AccordionItem

PropDescriptionTypeDefaultRequired
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
disabledWhether or not an accordion item is disabled from user interaction. @defaultValue false
boolean
----False
valueA string value for the accordion item. All items within an accordion should use a unique value.
string
----
True
asChild
boolean
----False

AccordionHeader

PropDescriptionTypeDefaultRequired
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False

AccordionTrigger

PropDescriptionTypeDefaultRequired
asChild
boolean
----False
density
"default" | "loose" | "compact" | ({ "@sm"?: "default" | "loose" | "compact"; "@md"?: "default" | "loose" | "compact"; "@lg"?: "default" | "loose" | "compact"; "@xl"?: "default" | "loose" | "compact"; ... 20 more ...; "@initial"?: "default" | ... 1 more ... | "compact"; } & { ...; })
----False
forcefocus
(boolean | "true" | ({ "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; "@notMd"?: boolean | "true"; ... 17 more ...; "@initial"?: boolean | "true"; } & { ...; })) & boolean
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
Edit this page on GitHub.