# Collapsible

A single collapsible panel controlled by a trigger button.

- Category: Core Elements
- Page: https://wunderui.com/components/collapsible
- Tier: Free

## Install

```bash
npx wunderui-cli add collapsible
```

## Import

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

## Minimal usage

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.

## Usage

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

export function Example() {
  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>
  )
}
```

## 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

- [Accordion](https://wunderui.com/components/accordion) for a list of several sections, such as an FAQ or grouped settings
- [Tabs](https://wunderui.com/components/tabs) for peer views of one object that people switch between
- [Dialog](https://wunderui.com/components/dialog) for a task that must block the page until it is done

## Keyboard

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

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous trigger, and to a control placed beside it with `CollapsibleRow`. |
| `Enter` or `Space` | Opens or closes the panel of the focused trigger. |

## Behavior

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

- `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.
- `CollapsibleTrigger`: 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.
- `Icon`: The optional icon before the label. It is decorative and takes the text colour.
- `Label`: 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.
- `Count`: The count badge after the label. It must equal the number of rows in the panel.
- `Indicator`: The chevron that flips when the panel opens, or the plus and minus box. The default is the chevron in both appearances.
- `CollapsibleRow`: Puts a control beside the trigger, never inside it. The action slot takes a button such as Edit.
- `CollapsibleContent`: 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.
- `CollapsibleFeedback`: 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.
- 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.
- 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.
- 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.
- 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 nest more than one level. For deeper structures use a tree view or separate pages.
- Don't add a height transition to CollapsibleContent. It already animates with motion tokens, and a second animation fights it.
- 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

| Prop | Type | Default | Description |
|---|---|---|---|
| appearance | "row" \| "inline" |  | `row` is a full-width trigger row, `inline` a link-style trigger that hugs its label. Without it the trigger keeps the legacy plus and minus box and ignores `icon`, `description`, `summary` and `count`. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultOpen | boolean | false | Whether the collapsible panel is initially open. To render a controlled collapsible, use the `open` prop instead. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| onOpenChange | ((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void) |  | Event handler called when the panel is opened or closed. |
| open | boolean |  | Whether the collapsible panel is currently open. To render an uncontrolled collapsible, use the `defaultOpen` prop instead. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### CollapsibleContent

| Prop | Type | Default | Description |
|---|---|---|---|
| align | "title" \| "start" | "start" | `start` lines the panel up with the trigger text, `title` with the label after a leading icon. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| hiddenUntilFound | boolean | false | Allows the browser's built-in page search to find and expand the panel contents. Overrides the `keepMounted` prop and uses `hidden="until-found"` to hide the element without removing it from the DOM. |
| keepMounted | boolean | false | Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when `hiddenUntilFound` is used. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### CollapsibleFeedback

| Prop | Type | Default | Description |
|---|---|---|---|
| kind* | "loading" \| "empty" \| "error" |  | `loading` shows skeleton lines and a label, `empty` a title, a description and an action, `error` an announced message with a warning icon and an action such as Retry. |
| action | React.ReactNode |  | A button or link shown under the message, such as Retry or Add attachment. |
| className | string |  | Classes for the feedback wrapper. |
| description | React.ReactNode |  | One sentence under the title: what is missing, or what to do next. |
| loadingLabel | string |  | The text under the skeleton lines while `kind="loading"`. Defaults to Loading…. |
| title | React.ReactNode |  | The heading of an `empty` or `error` message. |

### CollapsibleRow

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The `CollapsibleTrigger` the action sits beside. |
| action | React.ReactNode |  | A control shown beside the trigger, such as a plain small Button. It is never inside the trigger. |
| className | string |  | Classes for the row that holds the trigger and the action. |

### CollapsibleTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| count | number |  | Renders a badge counter. |
| description | React.ReactNode |  | Optional second line under the label. |
| icon | React.ReactNode |  | Optional leading decorative icon. |
| indicator | "button" \| "chevron" |  | "button" = the Plus/Minus box, "chevron" = a chevron that flips. |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| summary | React.ReactNode |  | Shown only while the panel is closed. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Appearance: row and inline, with a chevron or a plus and minus indicator

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

export function Example() {
  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>
  )
}
```

### Trigger: label, icon, description, count, summary and action

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

export function Example() {
  return (
    <Collapsible appearance="row" defaultOpen>
      <CollapsibleTrigger>Advanced settings</CollapsibleTrigger>
      <CollapsibleContent>These options apply to every project in the workspace.</CollapsibleContent>
    </Collapsible>
  )
}
```

### Content: files, order lines, activity and nested

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

export function Example() {
  return (
    <Collapsible appearance="row" defaultOpen>
      <CollapsibleTrigger count={4}>Attachments</CollapsibleTrigger>
      <CollapsibleContent>
        <ul className="flex flex-col gap-2">
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">quarterly-report.xlsx</span>
            <span className="text-xs">2.4 MB</span>
          </li>
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">brand-guidelines.pdf</span>
            <span className="text-xs">8.1 MB</span>
          </li>
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">onboarding-flow.png</span>
            <span className="text-xs">1.2 MB</span>
          </li>
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">roadmap-2027.pdf</span>
            <span className="text-xs">3.7 MB</span>
          </li>
        </ul>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

### States: default, hover, pressed, focus visible and disabled, closed and open

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

export function Example() {
  return (
    <Collapsible appearance="row">
      <CollapsibleTrigger>Payment methods</CollapsibleTrigger>
      <CollapsibleContent>Cards and bank accounts used for invoices.</CollapsibleContent>
    </Collapsible>
  )
}
```

### Content state: ready, loading, empty and error

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

export function Example() {
  return (
    <Collapsible appearance="row" defaultOpen>
      <CollapsibleTrigger count={4}>Attachments</CollapsibleTrigger>
      <CollapsibleContent>
        <ul className="flex flex-col gap-2">
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">quarterly-report.xlsx</span>
            <span className="text-xs">2.4 MB</span>
          </li>
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">brand-guidelines.pdf</span>
            <span className="text-xs">8.1 MB</span>
          </li>
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">onboarding-flow.png</span>
            <span className="text-xs">1.2 MB</span>
          </li>
          <li className="flex items-center justify-between gap-4">
            <span className="text-foreground">roadmap-2027.pdf</span>
            <span className="text-xs">3.7 MB</span>
          </li>
        </ul>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

## In context

### Advanced settings in a form: optional settings stay out of the way

The name is all most people need. The retention and archiving switches sit behind a trigger that says what is inside.

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"

export function ProjectForm() {
  return (
    <form className="flex flex-col gap-4">
      <div className="flex flex-col gap-2">
        <Label htmlFor="project-name">Project name</Label>
        <Input id="project-name" defaultValue="Northstar" />
      </div>
      <Collapsible appearance="row">
        <CollapsibleTrigger description="Retention, archiving and public pages">Advanced settings</CollapsibleTrigger>
        <CollapsibleContent>
          <div className="flex flex-col gap-3">
            <div className="flex items-center justify-between gap-4">
              <Label htmlFor="retention">Keep deleted tasks for 30 days</Label>
              <Switch id="retention" defaultChecked />
            </div>
            <div className="flex items-center justify-between gap-4">
              <Label htmlFor="archive">Archive finished sprints</Label>
              <Switch id="archive" />
            </div>
          </div>
        </CollapsibleContent>
      </Collapsible>
      <div className="flex justify-end gap-2">
        <Button type="button" variant="plain">Cancel</Button>
        <Button type="submit">Create project</Button>
      </div>
    </form>
  )
}
```

### Order summary in a checkout: the total stays visible while it is closed

The item count and total show next to the closed trigger and disappear when the lines open.

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"
import { Button } from "@/components/ui/button"

export function OrderSummary() {
  return (
    <div className="flex flex-col gap-4">
      <Collapsible appearance="row">
        <CollapsibleTrigger summary="3 items · $84.00">Order summary</CollapsibleTrigger>
        <CollapsibleContent>
          <ul className="flex flex-col gap-2">
            <li className="flex items-center justify-between gap-4">
              <span className="text-foreground">Design system, 1 seat</span>
              <span>$54.00</span>
            </li>
            <li className="flex items-center justify-between gap-4">
              <span className="text-foreground">Domain, wunderui.com</span>
              <span>$12.00</span>
            </li>
            <li className="flex items-center justify-between gap-4">
              <span className="text-foreground">Priority support</span>
              <span>$18.00</span>
            </li>
          </ul>
        </CollapsibleContent>
      </Collapsible>
      <Button>Pay $84.00</Button>
    </div>
  )
}
```

### Attachments in a ticket: the content loads when the section opens

Opening the section starts the request. The first one fails and offers Retry, the second fills the list and shows the count.

```tsx
import { useEffect, useState } from "react"
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleFeedback,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"
import { Button } from "@/components/ui/button"

export function TicketAttachments() {
  const [status, setStatus] = useState<"idle" | "loading" | "error" | "ready">("idle")
  const [attempt, setAttempt] = useState(0)

  // Stand-in for a request: the first one fails, the retry succeeds.
  useEffect(() => {
    if (status !== "loading") return
    const timer = window.setTimeout(() => setStatus(attempt === 0 ? "error" : "ready"), 1200)
    return () => window.clearTimeout(timer)
  }, [status, attempt])

  const retry = () => {
    setAttempt(attempt + 1)
    setStatus("loading")
  }

  return (
    <Collapsible
      appearance="row"
      onOpenChange={(open) => {
        if (open && status === "idle") setStatus("loading")
      }}
    >
      <CollapsibleTrigger count={status === "ready" ? 4 : undefined}>Attachments</CollapsibleTrigger>
      <CollapsibleContent>
        {status === "loading" && <CollapsibleFeedback kind="loading" loadingLabel="Loading attachments…" />}
        {status === "error" && (
          <CollapsibleFeedback
            kind="error"
            title="Couldn’t load attachments"
            description="Check your connection and try again."
            action={<Button variant="link" size="sm" onClick={retry}>Retry</Button>}
          />
        )}
        {status === "ready" && (
          <ul className="flex flex-col gap-2">
            <li className="flex items-center justify-between gap-4">
              <span className="text-foreground">quarterly-report.xlsx</span>
              <span className="text-xs">2.4 MB</span>
            </li>
            <li className="flex items-center justify-between gap-4">
              <span className="text-foreground">brand-guidelines.pdf</span>
              <span className="text-xs">8.1 MB</span>
            </li>
            <li className="flex items-center justify-between gap-4">
              <span className="text-foreground">onboarding-flow.png</span>
              <span className="text-xs">1.2 MB</span>
            </li>
            <li className="flex items-center justify-between gap-4">
              <span className="text-foreground">roadmap-2027.pdf</span>
              <span className="text-xs">3.7 MB</span>
            </li>
          </ul>
        )}
      </CollapsibleContent>
    </Collapsible>
  )
}
```

### Shipping details under running text: a link-style trigger

The inline style sits under a sentence like a link and reveals one more line.

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

export function ShippingNote() {
  return (
    <div className="text-sm text-text-secondary">
      <p>Your order ships to the address on file.</p>
      <Collapsible appearance="inline">
        <CollapsibleTrigger>Shipping details</CollapsibleTrigger>
        <CollapsibleContent>Orders placed before 2 pm ship the same day. Express orders arrive the next working day.</CollapsibleContent>
      </Collapsible>
    </div>
  )
}
```

### Shipping address with an Edit button beside the trigger

A button never goes inside the trigger. CollapsibleRow places it next to it.

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleRow,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"
import { Button } from "@/components/ui/button"

export function ShippingAddress() {
  return (
    <Collapsible appearance="row" defaultOpen>
      <CollapsibleRow action={<Button variant="plain" size="sm">Edit</Button>}>
        <CollapsibleTrigger description="Nora Lindgren · 14 Garden Street, Berlin 10115">Shipping address</CollapsibleTrigger>
      </CollapsibleRow>
      <CollapsibleContent>Delivery to the front desk, Monday to Friday, 9 am to 5 pm. The courier calls before arriving.</CollapsibleContent>
    </Collapsible>
  )
}
```

## For AI agents

`get_component("collapsible")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
