Skip to content
WunderUI

Collapsible

Free

Show or hide one optional block of content behind a trigger.

npx wunderui-cli add collapsible

Playground

Order 4821 shipped on October 12 with tracking. Delivery takes up to three working days.

Click the trigger to close it.

Installation

bash
npx wunderui-cli add collapsible

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleFeedback,
  CollapsibleRow,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"
import type {
  CollapsibleAppearance,
  CollapsibleContentAlign,
  CollapsibleIndicator,
} from "@/components/ui/collapsible"

Then use it:

tsx
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

Use something else for

  • Accordion for a list of several sections, such as an FAQ or grouped settings
  • Tabs for peer views of one object that people switch between
  • Dialog for a task that must block the page until it is done

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.

Order 4821 shipped on October 12 with tracking. Delivery takes up to three working days.

Trigger

A trigger can carry an icon, a description, a count, a summary that shows only while closed, and a button beside it.

These options apply to every project in the workspace.

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

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

Keyboard interactions

The trigger is a native button, so the browser handles focus and activation.

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

Require two-step sign-in for everyone who can edit this project.
  • 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.

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

  • Optional

    The optional icon before the label. It is decorative and takes the text colour.

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

  • Optional

    The count badge after the label. It must equal the number of rows in the panel.

  • The chevron that flips when the panel opens, or the plus and minus box. The default is the chevron in both appearances.

  • data-slot="collapsible-row"Optional

    Puts a control beside the trigger, never inside it. The action slot takes a button such as Edit.

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

PropTypeDefaultDescription
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 .
defaultOpenbooleanfalseWhether the collapsible panel is initially open. To render a controlled collapsible, use the prop instead.
openboolean—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.
disabledbooleanfalseWhether 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.

PropTypeDefaultDescription
iconReactNode—Optional leading decorative icon.
descriptionReactNode—Optional second line under the label.
summaryReactNode—Shown only while the panel is closed.
countnumber—Renders a badge counter.
indicator"button" | "chevron"—"button" = the Plus/Minus box, "chevron" = a chevron that flips.
nativeButtonbooleantrueWhether 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.

PropTypeDefaultDescription
actionReactNode—A control shown beside the trigger, such as a plain small Button. It is never inside the trigger.
children requiredReactNode—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.

PropTypeDefaultDescription
align"title" | "start""start" lines the panel up with the trigger text, with the label after a leading icon.
keepMountedbooleanfalseWhether to keep the element in the DOM while the panel is hidden. This prop is ignored when is used.
hiddenUntilFoundbooleanfalseAllows 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.

PropTypeDefaultDescription
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.
titleReactNode—The heading of an or message.
descriptionReactNode—One sentence under the title: what is missing, or what to do next.
actionReactNode—A button or link shown under the message, such as Retry or Add attachment.
loadingLabelstring—The text under the skeleton lines while . Defaults to Loading….

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("collapsible")
Installnpx wunderui-cli add collapsible

The full library index for assistants is at /llms.txt.