Collapsible

v1.0.0 | View in Storybook

​

When to use

• You require a mutually exclusive optional or secondary block of content on a page (e.g. AI reasoning, advanced settings, an explanation, a preview).
• When the content is useful but not essential to the primary task.
• Expanding additional details for a single item, such as an expandable table row or a single product detail card.

​

When to use something else

• Multiple stacked expandable sections: use Accordion instead.
• Navigation or filtering: use Tabs or filter controls (Combobox, Select, etc.).
• Use a Tooltip or Popover for short, temporary visual explanations that floatingly overlay content without pushing surrounding elements down.
• Content the user almost always needs: show it by default as regular text; don’t hide it in a collapsible.

​

Dos and don’ts

• Do default to collapsed unless the collapsible content is the main purpose of the view.
• Do keep the trigger label descriptive — it should communicate what’s inside, not just say “See more”.
• Do reserve space or animate layout reflow smoothly to prevent sudden visual jumps for the user.
• Don’t nest Collapsibles — if you need layered disclosure, reconsider the information architecture.
• Don’t use it to hide errors, critical or required information or CTAs inside.

​

Behavior

• One trigger expands or collapses a single associated region; animation is optional but state (expanded/collapsed) must be exposed to assistive tech when it conveys meaning.
• Collapsibles directly push down subsequent inline content upon expansion and pull it back up upon collapse without changing parent layout boundaries.

​

Often used with

Separator when stacking multiple collapsible regions on one page.

​

Accessibility

• Trigger attributes: Ensure disclosure triggers are semantic <button> elements with aria-expanded="true|false" linked to the expandable container id via aria-controls.
• Focus retention: Do not automatically shift focus into the revealed content container upon expansion unless it contains immediate form fields requiring user input.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Default open

Use a Collapsible that starts expanded when the hidden content is important on first visit—for example, onboarding tips or the primary settings group—so users see it without an extra click.

​

Controlled

Use a controlled Collapsible when open and closed state must follow application logic—for example, syncing with URL parameters, a parent form, or programmatic expand and collapse.

​

Multiple

Stack multiple Collapsibles on a page when each section toggles independently—for example, advanced settings blocks or optional detail panels that users may open in any combination.

​

Disabled

Use a disabled Collapsible when the section is temporarily unavailable, and add helper text that explains why the trigger cannot be activated.

​

With rich content

Use a Collapsible with rich content when the expanded region includes formatted text, lists, or embedded controls—not just a short paragraph of plain copy.

​

Faq

Use a Collapsible for FAQ-style content where each question is a trigger and the answer stays hidden until the user expands that item.

​

Edge case empty

Handle an empty Collapsible region gracefully by hiding the trigger or showing a message when there is no content to reveal after expansion.

​

Edge case long text

Use the long-text Collapsible pattern when expanded content may run to several paragraphs, ensuring the trigger label stays concise while the body can scroll or wrap naturally.