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