Skip to main content

Overview

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

Use 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 a div; 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 to dimension="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) and defaults to normal. Reduced-motion preferences disable the transitions. 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.
boolean
default:"false"
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.