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 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.
- 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.
- 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.
Controlled vs uncontrolled open state: use controlled mode when URL, filters, or parent wizards must sync with disclosure.
- 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.
- Preserve open state across navigation only when product requirements say so; default collapsed for rarely used sections.
- Animations should respect
prefers-reduced-motion.
- 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.
- 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).
