Collapsible

Overview

A Collapsible is a single trigger row paired with a panel that height-animates open and closed. Three types cover the surfaces in the product: body for inline disclosure, heading for top-level section headers, and checklist for confirmable list items. The wrapper CollapsibleGroup stacks them into an accordion, with optional single-open behaviour when only one panel should be visible at a time.

Anatomy

A trigger row with three slots, an optional panel underneath, and a 1 px divider that runs across the bottom (suppressed on the last item).

Types

Three types share the same trigger contract — only the geometry, weight, and indicator change.

Positions

The bottom divider is on by default and dropped on the last row. Inside CollapsibleGroup this happens automatically; outside of a group, pass isLast on the final item.

Status pill

A status pill in the trigger row signals that the panel beneath carries an action item. Use a tone-warning Badge — the only place a row earns a coloured pill in this component.

Accordion

Wrap a stack of Collapsibles in CollapsibleGroup to build an accordion. Pass single to limit the group to one open panel at a time. The wrapper handles the last-row divider for you.

In product

A real onboarding checklist. The heading-type row contains a three-step checklist; each row is independently checkable and independently expandable so the user can confirm completion without losing the instructions.

Motion

The panel uses a grid-template-rows transition (0fr → 1fr) so the height animates without measurement and adapts to whatever the panel actually contains. 220 ms, cubic-bezier(0.22, 0.61, 0.36, 1) (ease-out-quart). Reduced-motion users get an instant reveal.

/* The panel grid transitions between 0fr and 1fr.
 * The inner div carries overflow:hidden so the content
 * is clipped while the row collapses. */
.collapsible-panel {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 220ms cubic-bezier(0.22, 0.61, 0.36, 1);
}

.collapsible-panel[data-open='true'] {
  grid-template-rows: 1fr;
}

.collapsible-panel > div {
  overflow: hidden;
}

@media (prefers-reduced-motion: reduce) {
  .collapsible-panel { transition: none; }
}

Behavior

• 01Click anywhere on the trigger row. The trigger is the entire row, not just the icon. The bigger tap target matters on mobile and reduces precision-pointing on dense lists.
• 02Checklist taps split. Inside the checklist type, clicking the checkbox toggles the checked state without expanding the panel. Click anywhere else on the row to expand.
• 03Single-open closes peers. In a single-open group, opening one row closes any other open row in the same group. The closing animation runs to completion before the opening one starts so the page never jumps.
• 04Closed panels are hidden, not absent. The panel content stays in the DOM with visibility: hidden implied by the 0 row height — search-in-page (Cmd-F) still finds text inside closed panels and opens the row containing it.
• 05URL hash deep-links open. When the URL hash matches an item's id, the page opens that item on load and scrolls to it. This is how an FAQ question becomes a shareable link.

Accessibility

• Roles: the trigger is a native <button> with aria-expanded tracking the open state and aria-controls pointing at the panel id. The panel is a role="region" labelled by the trigger.
• Keyboard: Enter / Space toggles the current row. Tab / Shift+Tab moves focus through triggers. Inside a single-open group, focus stays on the activated trigger after the toggle so the user can step through one row at a time.
• Focus visibility: the trigger uses a 2 px offset focus ring in border.selected. On click the ring is suppressed via :focus-visibleso mouse and keyboard read differently — keyboard users see the ring; mouse users don't.
• Checkbox separation: the checklist type uses a nested button with role="checkbox" and aria-checked. The event bubble is stopped so the outer trigger doesn't toggle when the user activates the checkbox.
• Reduced motion: the grid-row transition is gated on prefers-reduced-motion: no-preference. Users who request reduced motion get an instant open / close with no height interpolation.
• Screen-reader announcements: changes to aria-expandedare announced as “expanded” / “collapsed” by every modern screen reader without an additional live region.

Code

The component is a thin pair: a Collapsible primitive (a self-contained trigger + panel) and a CollapsibleGroup wrapper that passes isLast and, in single mode, controls which item is open.

import { Collapsible, CollapsibleGroup } from "@flatpay-dk/ui";
import StorefrontIcon from "@mui/icons-material/StorefrontOutlined";

// Stand-alone — uncontrolled
<Collapsible type="body" title="How long does payout take?">
  <p>
    Funds for transactions captured before 22:00 CET land in your
    settlement account by 09:00 CET the next business day.
  </p>
</Collapsible>

// Heading row with a leading icon
<Collapsible
  type="heading"
  title="Storefront"
  leadingIcon={StorefrontIcon}
>
  <p>Trading hours, currency, language defaults.</p>
</Collapsible>

// Single-open accordion
<CollapsibleGroup single defaultIndex={0}>
  <Collapsible type="body" title="Item one">…</Collapsible>
  <Collapsible type="body" title="Item two">…</Collapsible>
  <Collapsible type="body" title="Item three">…</Collapsible>
</CollapsibleGroup>

// Checklist — checkbox state independent of expand state
const [done, setDone] = useState(false);
<Collapsible
  type="checklist"
  title="Verify your bank account"
  checked={done}
  onCheckedChange={setDone}
>
  <p>We'll send a small test deposit within two business days.</p>
</Collapsible>

Best practices

A few rules that catch the common misuses before they reach the screen.

Props

Collapsible

CollapsibleGroup

Related