Collapsible

Collapsible controls one expandable section, such as a disclosure, show-more block, or sidebar group.

Purpose

Collapsible controls one expandable section such as a disclosure, show-more block, or sidebar group. Use Accordion for a related collection of panels.

Basic usage

Preview build, typecheck and registry validation passed.

import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@/components/ui/collapsible";
import { Button } from "@/components/ui/button";

export function Example() {
  return (
    <Collapsible defaultOpen>
      <CollapsibleTrigger render={<Button variant="outline" />}>Details</CollapsibleTrigger>
      <CollapsiblePanel>Deployment checks passed.</CollapsiblePanel>
    </Collapsible>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/collapsible

Import

import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@/components/ui/collapsible";

Need the machine-readable source metadata? View registry JSON.

Usage

Collapsible is for a single disclosure area. Use Accordion when multiple related panels belong together.

import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@/components/ui/collapsible";
import { Button } from "@/components/ui/button";

export function Example() {
  return (
    <Collapsible defaultOpen>
      <CollapsibleTrigger render={<Button variant="outline" />}>Details</CollapsibleTrigger>
      <CollapsiblePanel>Deployment checks passed.</CollapsiblePanel>
    </Collapsible>
  );
}

Examples

Chevron rotation, the disabled state and trigger placement are props and compositions of the same primitive.

Chevron rotation

Any trigger child marked data-slot="collapsible-chevron" rotates while the panel is open. No per-trigger wiring needed.

<Collapsible>
  <CollapsibleTrigger className="flex w-full items-center justify-between gap-2 rounded-md border px-3 py-2 text-sm">
    Advanced options
    <ChevronDownIcon className="size-4" data-slot="collapsible-chevron" />
  </CollapsibleTrigger>
  <CollapsiblePanel>
    <p className="px-3 py-2 text-sm">
      The chevron rotates 180 degrees while the panel is open.
    </p>
  </CollapsiblePanel>
</Collapsible>

Disabled

<Collapsible disabled>
  <CollapsibleTrigger className="flex w-full cursor-not-allowed items-center justify-between gap-2 rounded-md border px-3 py-2 text-sm opacity-64">
    Details
    <ChevronDownIcon className="size-4" data-slot="collapsible-chevron" />
  </CollapsibleTrigger>
  <CollapsiblePanel>This content stays hidden while disabled.</CollapsiblePanel>
</Collapsible>

Show more

The trigger stays anchored while the additional text expands below it.

Siteplane UI bundles components, patterns and tokens in one place.

<Collapsible>
  <p>Siteplane UI bundles components, patterns and tokens in one place.</p>
  <CollapsibleTrigger className="flex w-fit items-center gap-1 font-medium text-primary text-sm hover:underline">
    Show more
    <ChevronDownIcon className="size-4" data-slot="collapsible-chevron" />
  </CollapsibleTrigger>
  <CollapsiblePanel>
    <p>The design system stays consistent while teams compose variants.</p>
  </CollapsiblePanel>
</Collapsible>

Filter group

ActiveArchived

<Collapsible defaultOpen>
  <CollapsibleTrigger className="flex w-full items-center justify-between gap-2 font-medium text-sm">
    Status
    <ChevronDownIcon className="size-4" data-slot="collapsible-chevron" />
  </CollapsibleTrigger>
  <CollapsiblePanel>
    <div className="grid gap-1.5 pt-2">
      <label className="flex items-center gap-2 text-sm" htmlFor="filter-active">
        <Checkbox defaultChecked id="filter-active" />
        Active
      </label>
      <label className="flex items-center gap-2 text-sm" htmlFor="filter-archived">
        <Checkbox id="filter-archived" />
        Archived
      </label>
    </div>
  </CollapsiblePanel>
</Collapsible>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

Use defaultOpen for uncontrolled initial state.
Use open with onOpenChange when another control or application state owns the disclosure state.
Set disabled on Collapsible to disable the trigger and state together.
CollapsiblePanel hiddenUntilFound keeps collapsed content available to browser find-in-page and lets the browser reveal a matching panel.
Keep trigger and panel inside the same root.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

Panel height uses --collapsible-panel-height with native starting and ending styles.
Keep the preview or product composition top-anchored so opening expands downward instead of recentering the entire control.
Chevron rotation and pointer states are additive composition behavior; do not nest a second height or opacity animation around the panel.
System and provider reduced-motion modes remove panel and chevron transition interpolation through the primitive and global contract.

Accessibility

Give every trigger visible text or an accessible label.
Keep trigger and panel connected through the Base UI context.
Disabled state remains recognizable and cannot activate the panel.
Use hiddenUntilFound when collapsed documentation must remain searchable.

Implementation Guidance

Do not create toggle divs in place of CollapsibleTrigger and CollapsiblePanel.
Keep one state owner; do not mix controlled and uncontrolled props.
Avoid nested layout animations around the native panel transition.