Collapsible
FreeShow or hide one optional block of content behind a trigger.
npx wunderui-cli add collapsiblePlayground
Click the trigger to close it.
Installation
npx wunderui-cli add collapsibleWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Collapsible,
CollapsibleContent,
CollapsibleFeedback,
CollapsibleRow,
CollapsibleTrigger,
} from "@/components/ui/collapsible"
import type {
CollapsibleAppearance,
CollapsibleContentAlign,
CollapsibleIndicator,
} from "@/components/ui/collapsible"Then use it:
import {
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
} from "@/components/ui/collapsible"
export function OrderDetails() {
return (
<Collapsible appearance="row" defaultOpen>
<CollapsibleTrigger>Order details</CollapsibleTrigger>
<CollapsibleContent>Order 4821 shipped on October 12 with tracking. Delivery takes up to three working days.</CollapsibleContent>
</Collapsible>
)
}Expected result: You see a row with Order details and a chevron. The panel is open, and a click on the row closes it.
When to use
Use Collapsible for
- One optional block that people open on demand, such as advanced options or a long description
- A short summary that opens into its details, such as an order summary in a checkout
- A link-style disclosure under running text, such as shipping details
Appearance
A full-width row for a section header, or a link-style trigger that hugs its label. Both use a chevron by default, and a plus and minus box is the other option.
Trigger
A trigger can carry an icon, a description, a count, a summary that shows only while closed, and a button beside it.
- quarterly-report.xlsx2.4 MB
- brand-guidelines.pdf8.1 MB
- onboarding-flow.png1.2 MB
- roadmap-2027.pdf3.7 MB
Content
The panel holds any content, such as files, order lines or activity. One collapsible can sit inside another, one level deep.
- quarterly-report.xlsx2.4 MB
- brand-guidelines.pdf8.1 MB
- onboarding-flow.png1.2 MB
- roadmap-2027.pdf3.7 MB
- Design system, 1 seat$54.00
- Domain, wunderui.com$12.00
- Priority support$18.00
- Nora Lindgren commented on the roadmap2 hours ago
- Daniel Okafor uploaded brand-guidelines.pdfYesterday
- Priya Raman changed the due dateOct 28
States and content state
Hover, pressed, focus and disabled, with the panel closed and open, plus what it shows while loading, empty or failed.
States
Content state
- quarterly-report.xlsx2.4 MB
- brand-guidelines.pdf8.1 MB
- onboarding-flow.png1.2 MB
- roadmap-2027.pdf3.7 MB
Loading attachments…
No attachments yet
Files you add will appear here.
Check your connection and try again.
Keyboard interactions
The trigger is a native button, so the browser handles focus and activation.
- TaborShift+Tab
- Moves focus to the next or previous trigger, and to a control placed beside it with .
- EnterorSpace
- Opens or closes the panel of the focused trigger.
Behavior and motion
What the collapsible does with state, content, the DOM and motion.
- Disabled
- Disabling the Collapsible dims the trigger to 40 % and stops it from toggling.
- Closed panels are not in the DOM
- A closed panel is not rendered by default, so its text is missing from the server HTML and page search, and form values inside it are lost on close. Keep it mounted, or let find-in-page open it.
- Always set the look
- Appearance is optional. Without it the trigger keeps the legacy look, a bare label with the plus and minus box, and ignores icon, description, summary and count, so set it in new code.
- Summary and count
- The summary shows only while the panel is closed and hides when it opens, so use it for what people need before they open it. The count stays visible and must equal the rows inside.
- Controls beside the trigger
- A trigger is a button and cannot hold another button. CollapsibleRow puts an action next to it, and the action has its own focus stop.
- Nesting
- One collapsible can sit inside the panel of another, and its panel then opens 16 px below its trigger. Do not nest further.
- Opening and closing
- The panel follows the height of its content on a grid-row transition, without measuring it. The chevron turns 180 degrees.
- Reduced motion
- With reduced motion the panel opens and closes instantly and the chevron flips without turning. The colour changes of hover and pressed stay.
Anatomy
The parts a trigger and its panel are made of, numbered in the figure.
- data-slot="collapsible"
Holds the open state and wraps the trigger and the panel. Appearance is row (a full-width trigger) or inline (a link-style trigger), and without it the trigger keeps the plus and minus box.
- 1data-slot="collapsible-trigger"
The header, a button that reports whether it is expanded. It can show a leading icon, a second line, a summary while closed, a count badge and an indicator, and hover and press change its fill.
- 2Optional
The optional icon before the label. It is decorative and takes the text colour.
- 3
The children of the trigger. Name it after what is hidden, since it is the accessible name of the button and stays the same when the panel opens.
- 4Optional
The count badge after the label. It must equal the number of rows in the panel.
- 5
The chevron that flips when the panel opens, or the plus and minus box. The default is the chevron in both appearances.
- 6data-slot="collapsible-row"Optional
Puts a control beside the trigger, never inside it. The action slot takes a button such as Edit.
- 7data-slot="collapsible-content"
The panel. It opens on a grid-row transition, so nothing is measured, and sits 24 px below the trigger (16 px when nested), lined up with the trigger text.
- data-slot="collapsible-feedback"Optional
The loading, empty and error content of a panel, with an optional action such as Retry.
Best practices
- Do
Pick row for a section header and inline for a link-style trigger under running text. Use one appearance per group of triggers.
- Do
Name the trigger after what is hidden, like Advanced options or Shipping details. Keep the title the same when it opens, and let only the indicator change.
- Do
Use the summary for what people need while the panel is closed, like 3 items and the total, and the count for the number of things inside. The count must equal the rows in the panel.
- Do
Keep fields a form needs outside the closed panel. A collapsed panel is easy to skip, and an error inside it stays out of sight.
- Do
Show loading, empty and error content with CollapsibleFeedback and offer an action such as Retry.
- Don’t
Don't put buttons or links inside CollapsibleTrigger, which is a button itself. Put an action beside it with CollapsibleRow.
- Don’t
Don't nest more than one level. For deeper structures use a tree view or separate pages.
- Don’t
Don't add a height transition to CollapsibleContent. It already animates with motion tokens, and a second animation fights it.
- Don’t
Don't stack several collapsibles to build an FAQ or a settings list. That is an Accordion, which also closes the open row.
API reference
Collapsible wraps the Base UI collapsible and passes its props on, such as open state and disabled on the root and keep mounted on the panel. Every part also takes className, style and render.
Holds the open state and wraps the trigger and the panel. Appearance is row (a full-width trigger) or inline (a link-style trigger), and without it the trigger keeps the plus and minus box.
| Prop | Type | Default | Description |
|---|---|---|---|
| appearance | "row" | "inline" | — | is a full-width trigger row, a link-style trigger that hugs its label. Without it the trigger keeps the legacy plus and minus box and ignores , , and . |
| defaultOpen | boolean | false | Whether the collapsible panel is initially open. To render a controlled collapsible, use the prop instead. |
| open | boolean | — | Whether the collapsible panel is currently open. To render an uncontrolled collapsible, use the prop instead. |
| onOpenChange | (open, eventDetails) => void | — | Event handler called when the panel is opened or closed. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
The header, a button that reports whether it is expanded. It can show a leading icon, a second line, a summary while closed, a count badge and an indicator, and hover and press change its fill.
| Prop | Type | Default | Description |
|---|---|---|---|
| icon | ReactNode | — | Optional leading decorative icon. |
| description | ReactNode | — | Optional second line under the label. |
| summary | ReactNode | — | Shown only while the panel is closed. |
| count | number | — | Renders a badge counter. |
| indicator | "button" | "chevron" | — | "button" = the Plus/Minus box, "chevron" = a chevron that flips. |
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). |
Puts a control beside the trigger, never inside it. The action slot takes a button such as Edit.
| Prop | Type | Default | Description |
|---|---|---|---|
| action | ReactNode | — | A control shown beside the trigger, such as a plain small Button. It is never inside the trigger. |
| children required | ReactNode | — | The the action sits beside. |
The panel. It opens on a grid-row transition, so nothing is measured, and sits 24 px below the trigger (16 px when nested), lined up with the trigger text.
| Prop | Type | Default | Description |
|---|---|---|---|
| align | "title" | "start" | "start" | lines the panel up with the trigger text, with the label after a leading icon. |
| keepMounted | boolean | false | Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when is used. |
| hiddenUntilFound | boolean | false | Allows the browser's built-in page search to find and expand the panel contents. Overrides the prop and uses to hide the element without removing it from the DOM. |
The loading, empty and error content of a panel, with an optional action such as Retry.
| Prop | Type | Default | Description |
|---|---|---|---|
| kind required | "loading" | "empty" | "error" | — | shows skeleton lines and a label, a title, a description and an action, an announced message with a warning icon and an action such as Retry. |
| title | ReactNode | — | The heading of an or message. |
| description | ReactNode | — | One sentence under the title: what is missing, or what to do next. |
| action | ReactNode | — | A button or link shown under the message, such as Retry or Add attachment. |
| loadingLabel | string | — | The text under the skeleton lines while . Defaults to Loading…. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("collapsible")npx wunderui-cli add collapsibleThe full library index for assistants is at /llms.txt.