Collapsible
Collapsible reveals one independent panel when controlled state, shared anatomy, or maintained motion adds value beyond native disclosure.
Overview and decision boundary
Use Collapsible for one independent disclosure when controlled state, shared anatomy, or maintained motion adds durable value.
Do not replace native details and summary when no shared state, motion, or anatomy is needed.
import { ChevronDown } from "@nerio-ui/adapters/icons";import { Icon } from "@nerio-ui/ui";import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@nerio-ui/ui/client";<Collapsible> <CollapsibleTrigger> Recovery keys <Icon aria-hidden icon={ChevronDown} /> </CollapsibleTrigger> <CollapsiblePanel> Generate a new set before revoking the current recovery keys. </CollapsiblePanel></Collapsible>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add collapsibleimport { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@nerio-ui/ui/client";Usage
import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@nerio-ui/ui/client";<Collapsible> <CollapsibleTrigger>Recovery keys</CollapsibleTrigger> <CollapsiblePanel>Generate and store recovery keys securely.</CollapsiblePanel></Collapsible>Variants
| Path | Use |
|---|---|
Collapsible | One controlled or uncontrolled disclosure with maintained anatomy and motion. |
details / summary | Simple native disclosure with no shared abstraction requirement. |
Anatomy
| Slot | Purpose |
|---|---|
root | Owns one open state and the disabled boundary. |
trigger | Native button associated with the panel. |
panel | Hidden content that unmounts when closed by default. |
States
| State | Behavior |
|---|---|
Closed | Panel is removed by default, including interactive descendants. |
Open | Measured height and opacity reveal the complete content. |
Disabled | The visible trigger cannot change state. |
Reduced motion | The panel changes state immediately without travel. |
Motion
- Panel height uses the Base UI measured height variable and shared reveal tokens.
- Opacity reinforces state without carrying essential information.
- Reduced motion makes the state change immediate.
Accessibility
- Uses the Base UI Collapsible primitive with a native type=button trigger by default.
- The trigger owns aria-expanded and aria-controls while the panel owns the corresponding stable ID.
- Closed panels are unmounted by default so hidden interactive descendants do not remain focusable; keepMounted and hiddenUntilFound preserve browser-hidden semantics.
- Supports one controlled or uncontrolled open state and a disabled root without duplicating Base UI state.
- Enter, Space, pointer, and touch activation toggle the panel while focus remains on the trigger.
- Height and opacity motion use shared disclosure tokens and become immediate under reduced motion.
- Use native details and summary when controlled state, maintained motion, or shared anatomy adds no durable value.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Use |
|---|---|
open / defaultOpen | Controlled or uncontrolled open state. |
onOpenChange | Receives the next state and cancellable Nerio event details. |
disabled | Disables the complete disclosure. |
keepMounted / hiddenUntilFound | Preserves browser-hidden content for state or page search. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | collapsible installs 6 source files into the configured components directory. |
Base UI | collapsible |
Registry dependencies | None. |
Package dependencies | @base-ui/react, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Collapsible owns one disclosure only; grouped expansion belongs to Accordion.
- Content, persistence, fetching, analytics, and product workflow remain consumer-owned.
Do / do not
Do
Use one concise trigger for content that can safely leave the reading flow.
Do not
Wrap simple native disclosure or grouped sections in one oversized component.
Related components
Tokens
| Token | Controls |
|---|---|
--n-disclosure-background / border / radius | Disclosure surface and boundary. |
--n-disclosure-trigger-min-height / padding-inline | Density-aware trigger geometry. |
--n-disclosure-panel-padding-inline / foreground | Panel content rhythm and tone. |
--n-disclosure-focus-ring | Inset trigger focus treatment. |
--n-motion-reveal-duration / easing | Measured-height state transition. |