# Collapsible

An interactive component which expands and collapses a panel.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="collapsible" />

<ComponentPreview name="collapsible" title="collapsible.tsx" previewClassName="h-auto py-8">
<CollapsibleDemo />
</ComponentPreview>

Collapsible reveals or hides a single panel triggered by a button. It is the primitive behind accordion rows and nested file trees.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add collapsible
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="collapsible" title="components/ui/collapsible.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

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

```tsx title="collapsible.tsx"
<Collapsible>
  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
  <CollapsibleContent>Hidden content.</CollapsibleContent>
</Collapsible>
```

## Examples [#examples]

### Basic [#basic]

Pass `as` on the trigger to render a custom element.

<ComponentPreview name="collapsible-basic" title="collapsible-basic.tsx" src="examples/collapsible-basic.tsx" previewClassName="h-auto py-8">
<h />
</ComponentPreview>

### File tree [#file-tree]

Compose nested collapsibles to build a tree.

<ComponentPreview name="collapsible-file-tree" title="collapsible-file-tree.tsx" src="examples/collapsible-file-tree.tsx" previewClassName="h-auto py-8">
<m />
</ComponentPreview>

## In context [#in-context]

### Details panel [#details-panel]

<ComponentPreview name="collapsible-details" title="collapsible-details.tsx" src="examples/collapsible-details.tsx">
<j />
</ComponentPreview>

## Motion [#motion]

Collapsible accepts a `motion` prop on the root, inherited by `CollapsibleContent`. Pass a per-item override on `CollapsibleContent` to diverge from the root.

```tsx
<Collapsible motion="200 ease-out">
  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
  <CollapsibleContent motion="300 cubic-bezier(0.4, 0, 0.2, 1)">Revealed content.</CollapsibleContent>
</Collapsible>
```

`motion` accepts `"off"`, `"150"`, `"150 ease-out"`, or `"150 cubic-bezier(0.4, 0, 0.2, 1)"`. The default is a 450ms smooth-out curve. `prefers-reduced-motion` wins and the reveal is instant.

## API Reference [#api-reference]

### Collapsible [#collapsible]

<PropsTable rows={[{"name":"defaultOpen","type":"boolean","default":"false","description":"Whether the panel starts expanded."},{"name":"open","type":"boolean","description":"Controlled open state."},{"name":"onOpenChange","type":"(open: boolean) => void","description":"Called when the panel toggles."},{"name":"disabled","type":"boolean","default":"false","description":"Prevent toggling."},{"name":"motion","type":"string","description":"Motion string for the reveal. Pass off to disable."}]} />

### CollapsibleTrigger [#collapsibletrigger]

<PropsTable rows={[{"name":"as","type":"React.ElementType","description":"Renders a different root element or component. Defaults to button."}]} />

### CollapsibleContent [#collapsiblecontent]

<PropsTable rows={[{"name":"motion","type":"string | false","description":"Per-content override for the reveal motion. Pass false to disable."}]} />

## Controlled [#controlled]

```tsx
const [open, setOpen] = React.useState(false);

<Collapsible onOpenChange={setOpen} open={open}>
  {/* ... */}
</Collapsible>
```

## Keyboard [#keyboard]

| Key | Action |
| :-- | :-- |
| `Space` / `Enter` | Toggle the panel |

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `collapsible`, `collapsible-trigger`, `collapsible-content` |
| `data-state` | `open` \| `closed` |
| `data-disabled` | Present on disabled root, trigger, and content |

## Accessibility [#accessibility]

- Triggers expose `aria-expanded` and `aria-controls`; content is labeled with `aria-labelledby` and carries `role="region"`.
- Keyboard: `Enter` and `Space` toggle the panel.
- Provide a descriptive trigger label or `aria-label`.

## Best Practices [#best-practices]

- **Use for optional detail.** Content that must be visible on load belongs on the page.
- **Keep the trigger visible.** Never hide the trigger inside the content.
- **Default closed for long content.** Default open for short, always-relevant blocks.
- **Do not nest collapsibles.** Two levels is hard to track; use Accordion for nested groups.

## Related Components [#related-components]

- [Accordion](/docs/components/web/accordion): multiple collapsible sections
- [Tabs](/docs/components/tabs): swap content panes