Collapsible exposes Base UI’s Root, Trigger, and Panel contracts. Root owns expansion state, Trigger supplies keyboard activation and the panel relationship, and Panel owns animation and content lifetime.
Usage
defaultOpen for uncontrolled expansion. Use open and onOpenChange when the application owns the state. The callback receives the requested boolean and Base UI event details, including reason, event, and cancel(). Canceling a change preserves the current state. An externally controlled panel can omit Trigger when its state comes from another control or application condition.
Triggers inherit Root’s disabled state and can override it with their own disabled prop. The native trigger supports Enter and Space and supplies aria-expanded and aria-controls automatically. Give each trigger a meaningful accessible name.
Anatomy
Native customization
Root and Panel render adiv; Trigger renders a button. Each part accepts native attributes, handlers, className, style, refs, and Base UI render composition. Class and style callbacks receive the part’s state. Forward all supplied props and the ref from custom render components. Set nativeButton={false} when Trigger renders a non-button element.
Public types include CollapsibleRootProps, CollapsibleTriggerProps, CollapsiblePanelProps, the three part state types, and CollapsibleRootChangeEventDetails and CollapsibleRootChangeEventReason.
Animation and content lifetime
Panel defaults todimension="height". Use dimension="width" for horizontal expansion and constrain the content’s width when needed. containAnimation defaults to true, clips overflow, and lays content out in a column. Set it to false when content needs to overflow during the transition.
Panel’s duration chooses a theme preset (instant, fast, normal, or slow). For independent timings, use native style={{ transitionDuration: '0.4s, 0.2s' }}. The first duration controls size and the second controls opacity. Reduced-motion preferences disable the transitions, including custom timings.
Panel unmounts after closing by default. Use keepMounted to preserve local content state while hiding the closed panel. hiddenUntilFound lets browser page search reveal closed content and takes precedence over keepMounted.
Props
Collapsible.Root
string | ((state: CollapsibleRootState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
boolean
default:"false"
Initial uncontrolled expansion state.
boolean
default:"false"
Default disabled state inherited by the triggers in this root.
((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void)
Called with the requested open state and cancelable Base UI event details.
boolean
Controlled expansion state. Use defaultOpen for uncontrolled state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsibleRootState>
Replaces the root div. Forward the supplied props and ref.
CSSProperties | ((state: CollapsibleRootState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Collapsible.Trigger
string | ((state: CollapsibleTriggerState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
boolean
Disables this trigger.
boolean
default:"true"
Set to false when render replaces the native button with another element.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsibleTriggerState>
Replaces the linked trigger button. Forward the supplied props and ref.
CSSProperties | ((state: CollapsibleTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Collapsible.Panel
string | ((state: CollapsiblePanelState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
boolean
default:"true"
Clips overflowing content during expansion and uses a column layout.
"height" | "width"
default:"height"
Dimension animated when the panel opens and closes.
"fast" | "instant" | "normal" | "slow"
default:"normal"
Theme timing preset for both size and opacity. Native style can customize transition timing.
Uses hidden until-found so browser page search can reveal the contents. Overrides keepMounted.
boolean
default:"false"
Keeps the closed panel mounted and hidden, preserving local content state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CollapsiblePanelState>
Replaces the animated panel div. Forward the supplied props and ref.
CSSProperties | ((state: CollapsiblePanelState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.