Collapsible

Usage

Overview

Collapsible, CollapsibleTrigger, and CollapsibleContent implement show/hide regions without full accordion chrome—one independent disclosure block. Use them when supplementary detail should stay out of the default scan path but remain one click away, matching platform guidance to disclose progressively rather than overwhelming first load.

Caller transcript

Caller reports smoke from a neighboring apartment. Asked to stay on the line…

Caller is a female in her mid-30s, reporting heavy smoke from unit 4B at 118 Monroe Ave. She and her children have evacuated to the lobby.Dispatcher advised to remain outside, confirmed units en route, and requested updates on any visible flames or injuries.

When to use

Long-form sections on settings or detail panes where most users need only the summary.
Helper text, advanced fields, or debug panels that would clutter the default layout.
Single-section disclosure where accordion multi-panel semantics are unnecessary.

When not to use

Multiple mutually exclusive sections that should behave as one accordion—use Accordion.
Primary navigation or route changes—use Tabs, Tab nav, or side nav.
Critical instructions required to complete the task—keep them visible; collapsibles are for optional depth.

Variants

Controlled vs uncontrolled open state: use controlled mode when URL, filters, or parent wizards must sync with disclosure.

Content guidelines

Trigger labels should describe what expands (“Show advanced filters”, “Caller notes”) using formatMessage.
Avoid vague chevron-only triggers without visible text unless an icon button with title and tooltip is approved for density.

Behavior and states

Preserve open state across navigation only when product requirements say so; default collapsed for rarely used sections.
Animations should respect prefers-reduced-motion.

Best practices

Do pair the trigger with Interactable or Button via asChild for consistent focus and hit targets.
Do keep headings structured so screen reader users understand the relationship between trigger and content.
Don’t nest multiple independent collapsibles without headings—deep nesting disorients scanning.
Don’t hide validation errors exclusively inside collapsed regions.

Accessibility

Trigger must be keyboard operable and expose expanded/collapsed state.
Content region should be associated with the trigger for screen readers per Radix defaults; verify in component stories.
Ensure focus moves sensibly when content appears (avoid focus loss).

Accordion for stacked, optional single-open patterns.
Interactable for unified click/focus behavior.
Button for labeled triggers.

Circle / Accessibility

Collapsible / API and Development

On this page

Collapsible

Usage

Overview

Caller transcript

Caller reports smoke from a neighboring apartment. Asked to stay on the line…

When to use

Long-form sections on settings or detail panes where most users need only the summary.
Helper text, advanced fields, or debug panels that would clutter the default layout.
Single-section disclosure where accordion multi-panel semantics are unnecessary.

When not to use

Multiple mutually exclusive sections that should behave as one accordion—use Accordion.
Primary navigation or route changes—use Tabs, Tab nav, or side nav.
Critical instructions required to complete the task—keep them visible; collapsibles are for optional depth.

Variants

Controlled vs uncontrolled open state: use controlled mode when URL, filters, or parent wizards must sync with disclosure.

Content guidelines

Trigger labels should describe what expands (“Show advanced filters”, “Caller notes”) using formatMessage.
Avoid vague chevron-only triggers without visible text unless an icon button with title and tooltip is approved for density.

Behavior and states

Preserve open state across navigation only when product requirements say so; default collapsed for rarely used sections.
Animations should respect prefers-reduced-motion.

Best practices

Do pair the trigger with Interactable or Button via asChild for consistent focus and hit targets.
Do keep headings structured so screen reader users understand the relationship between trigger and content.
Don’t nest multiple independent collapsibles without headings—deep nesting disorients scanning.
Don’t hide validation errors exclusively inside collapsed regions.

Accessibility

Trigger must be keyboard operable and expose expanded/collapsed state.
Content region should be associated with the trigger for screen readers per Radix defaults; verify in component stories.
Ensure focus moves sensibly when content appears (avoid focus loss).

Accordion for stacked, optional single-open patterns.
Interactable for unified click/focus behavior.
Button for labeled triggers.

Circle / Accessibility

Collapsible / API and Development

On this page