XDS — Design System

Collapsible@xds/core v0.0.13 · XDSCollapsible

Usage

Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in XDSCollapsibleGroup for accordion behavior. For custom collapsible components, use the `useXDSCollapsible` hook directly (`xds hook useXDSCollapsible`).

ts
import {XDSCollapsible} from '@xds/core/Collapsible'

Best practices

Guidance	Practices
Do	Wrap each XDSCollapsible in an XDSCard for visual separation in accordion layouts.
Do	Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.
Do	Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.
Do	Start sections open (defaultIsOpen) when the content is likely needed on first view — don't make users click to see essential info.
Don't	Hide critical or required content behind a collapsible — users may not discover it.
Don't	Nest collapsibles more than two levels deep — it makes content hard to find and navigate.
Don't	Use a collapsible for a single short paragraph — just show the text directly instead.

Sub-components

Collapsible is a compound component with 2 sub-components.

XDSCollapsible

A primitive that makes any content collapsible — a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.

Prop	Type	Description
triggerrequired	ReactNode	Content shown in the trigger area (always visible).
children	ReactNode	Content that collapses and expands.
defaultIsOpen	boolean (default: true)	Default open state (uncontrolled).
isOpen	boolean	Controlled open state.
onOpenChange	(isOpen: boolean) => void	Callback invoked when the open state changes.
value	string	Identifier used for group coordination. Required when placed inside an XDSCollapsibleGroup.

XDSCollapsibleGroup

Coordinates multiple XDSCollapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element.

Prop	Type	Description
childrenrequired	ReactNode	XDSCollapsible instances to coordinate.
type	'single' \| 'multiple' (default: 'single')	Whether one or many items can be open simultaneously.
defaultValue	string \| string[]	Default open item(s) for uncontrolled usage. Use a string for single mode and an array for multiple mode.
value	string \| string[]	Controlled open item(s).
onChange	(value: string \| string[]) => void	Callback invoked when the set of open items changes.

Examples

Common configurations, variations, and states.

Collapsible — Controlled

Manage the open section from parent state. Use when the open state needs to sync with a URL param, form, or external control.

Collapsible — Multiple Mode

Several sections open at once. Use when users need to compare content across sections, like feature lists or pricing tiers.

Collapsible — Single Mode

Only one section open at a time. Use for settings pages or any list where expanding one item should close the others.

Collapsible — With Dividers

Collapsible sections separated by dividers instead of cards. Use for inline disclosure in detail panels or sidebar content where cards would add too much weight.

Usage

import {XDSCollapsible} from '@xds/core/Collapsible'

Best practices

Guidance	Practices
Do	Wrap each XDSCollapsible in an XDSCard for visual separation in accordion layouts.
Do	Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.
Do	Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.
Do	Start sections open (defaultIsOpen) when the content is likely needed on first view — don't make users click to see essential info.
Don't	Hide critical or required content behind a collapsible — users may not discover it.
Don't	Nest collapsibles more than two levels deep — it makes content hard to find and navigate.
Don't	Use a collapsible for a single short paragraph — just show the text directly instead.

Prop

Type

Description

triggerrequired

ReactNode

Content shown in the trigger area (always visible).

children

ReactNode

Content that collapses and expands.

defaultIsOpen

boolean (default: true)

Default open state (uncontrolled).

isOpen

boolean

Controlled open state.

onOpenChange

(isOpen: boolean) => void

Callback invoked when the open state changes.

value

string

Identifier used for group coordination. Required when placed inside an XDSCollapsibleGroup.

Prop

Type

Description

childrenrequired

ReactNode

XDSCollapsible instances to coordinate.

type

'single' | 'multiple' (default: 'single')

Whether one or many items can be open simultaneously.

defaultValue

string | string[]

Default open item(s) for uncontrolled usage. Use a string for single mode and an array for multiple mode.

value

string | string[]

Controlled open item(s).

onChange

(value: string | string[]) => void

Callback invoked when the set of open items changes.