XDS — Design System

XDSCollapsibleGroup@xds/core · Collapsible

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`).

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.

Anatomy

Element		Description
Trigger	required	The always-visible button that toggles the content. Shows a label and a chevron indicator.
Chevron		Animated arrow that rotates to show open or closed state.
Content		The area that hides or reveals when the trigger is clicked.

Import

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

Props

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.

Showcase source

tsx
'use client';
import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
import {XDSCard} from '@xds/core/Card';
import {XDSVStack} from '@xds/core/Layout';
import {XDSCenter} from '@xds/core/Center';
import {XDSText} from '@xds/core/Text';
export default function CollapsibleGroupShowcase() {
  return (
    <XDSCenter width={400}>
      <XDSCollapsibleGroup type="single" defaultValue="shipping">
        <XDSVStack gap={2} width="100%">
          <XDSCard>
            <XDSCollapsible trigger="Shipping Information" value="shipping">
              <XDSText type="body" color="secondary">
                Standard shipping takes 3–5 business days. Express shipping is
                available for an additional fee.
              </XDSText>
            </XDSCollapsible>
          </XDSCard>
          <XDSCard>
            <XDSCollapsible trigger="Return Policy" value="returns">
              <XDSText type="body" color="secondary">
                Items can be returned within 30 days of purchase. Items must be
                unused and in original packaging.
              </XDSText>
            </XDSCollapsible>
          </XDSCard>
          <XDSCard>
            <XDSCollapsible trigger="Payment Methods" value="payment">
              <XDSText type="body" color="secondary">
                We accept all major credit cards, PayPal, and bank transfers.
              </XDSText>
            </XDSCollapsible>
          </XDSCard>
        </XDSVStack>
      </XDSCollapsibleGroup>
    </XDSCenter>
  );
}