Collapsible

An interactive component that expands and collapses a panel.

Loan #2207

StatusOn loan
"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"
import { HStack, VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { leading, radius, space, text } from "@/theme/tokens.stylex"
import { CaretUpDownIcon } from "@phosphor-icons/react/dist/csr/CaretUpDown"

const styles = stylex.create({
  title: { fontSize: text.sm, lineHeight: leading.sm, fontWeight: 600 },
  root: { width: "100%", maxWidth: "22rem" },
  row: {
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
    paddingInline: space.s4,
    paddingBlock: space.s2,
    fontSize: text.sm,
    lineHeight: leading.sm,
  },
  content: { paddingBlockStart: space.s2 },
})

export default function CollapsibleDemo() {
  const [open, setOpen] = useState(false)

  return (
    <Collapsible open={open} onOpenChange={setOpen} xstyle={styles.root}>
      <VStack gap={2}>
        <HStack gap={4} align="center" justify="between" paddingInline={4}>
          <h4 {...stylex.props(styles.title)}>Loan #2207</h4>
          <CollapsibleTrigger
            render={<Button variant="ghost" size="icon" aria-label="Toggle details" />}
          >
            <CaretUpDownIcon aria-hidden="true" />
          </CollapsibleTrigger>
        </HStack>
        <HStack align="center" justify="between" xstyle={styles.row}>
          <Text tone="muted">Status</Text>
          <Text weight="medium">On loan</Text>
        </HStack>
      </VStack>
      <CollapsibleContent xstyle={styles.content}>
        <VStack gap={2}>
          <VStack xstyle={styles.row}>
            <Text render={<p />} weight="medium">
              Borrower
            </Text>
            <Text render={<p />} tone="muted">
              Emmy Noether, Göttingen
            </Text>
          </VStack>
          <VStack xstyle={styles.row}>
            <Text render={<p />} weight="medium">
              Items
            </Text>
            <Text render={<p />} tone="muted">
              1x Disquisitiones Arithmeticae
            </Text>
          </VStack>
        </VStack>
      </CollapsibleContent>
    </Collapsible>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/collapsible

Needs the arene setup first.

Usage

import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"
<Collapsible>
  <CollapsibleTrigger>What changed in 2.4?</CollapsibleTrigger>
  <CollapsibleContent>Offline editing, and a fix for sync on slow networks.</CollapsibleContent>
</Collapsible>

Composition

Collapsible
├── CollapsibleTrigger
└── CollapsibleContent

CollapsibleTrigger is unstyled. Pass render={<Button />} to make it a button. CollapsibleContent renders the Base UI Panel around an inner element that holds the content box. The panel animates its height over 300ms when it opens and closes.

Put the space above or below the panel inside it, as padding on CollapsibleContent, not as a gap or margin around it. A gap outside stays at full size while the panel shrinks to nothing, then disappears when the panel unmounts, so the close ends with a jump.

Controlled state

Pass open and onOpenChange to keep the open state in your own component.

import { useState } from "react"

export function Example() {
  const [open, setOpen] = useState(false)

  return (
    <Collapsible open={open} onOpenChange={setOpen}>
      <CollapsibleTrigger>Toggle</CollapsibleTrigger>
      <CollapsibleContent>Content</CollapsibleContent>
    </Collapsible>
  )
}

Basic

Spread collapsibleStyles.chevron on an icon inside the trigger to turn it with the panel.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Card, CardContent } from "@/components/ui/card"
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  collapsibleStyles,
} from "@/components/ui/collapsible"
import { VStack } from "@/components/ui/stack"
import { space } from "@/theme/tokens.stylex"
import { CaretDownIcon } from "@phosphor-icons/react/dist/csr/CaretDown"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  trigger: { width: "100%", justifyContent: "space-between" },
  content: { paddingInline: space.s2_5, paddingBlockEnd: space.s2_5 },
})

export default function CollapsibleBasic() {
  return (
    <Card xstyle={widths.sm}>
      <CardContent>
        <Collapsible>
          <CollapsibleTrigger render={<Button variant="ghost" xstyle={styles.trigger} />}>
            Release notes
            <CaretDownIcon aria-hidden="true" {...stylex.props(collapsibleStyles.chevron)} />
          </CollapsibleTrigger>
          <CollapsibleContent xstyle={styles.content}>
            <VStack gap={2} align="start">
              <p>Version 2.4 adds offline editing and fixes sync on slow networks.</p>
              <Button size="xs">Learn more</Button>
            </VStack>
          </CollapsibleContent>
        </Collapsible>
      </CardContent>
    </Card>
  )
}

Settings panel

An icon button shows or hides the second row of fields.

Corner radius
Give each corner its own value in pixels.
"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"
import { Input } from "@/components/ui/input"
import { HStack, VStack } from "@/components/ui/stack"
import { space } from "@/theme/tokens.stylex"
import { ArrowsOutIcon } from "@phosphor-icons/react/dist/csr/ArrowsOut"
import { ArrowsInIcon } from "@phosphor-icons/react/dist/csr/ArrowsIn"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  content: { paddingBlockStart: space.s2 },
})

export default function CollapsibleSettings() {
  const [open, setOpen] = useState(false)

  return (
    <Card size="sm" xstyle={widths.xs}>
      <CardHeader>
        <CardTitle>Corner radius</CardTitle>
        <CardDescription>Give each corner its own value in pixels.</CardDescription>
      </CardHeader>
      <CardContent>
        <Collapsible open={open} onOpenChange={setOpen}>
          <HStack gap={2} align="start">
            <VStack grow>
              <HStack gap={2}>
                <Input aria-label="Top left radius" placeholder="0" defaultValue={0} />
                <Input aria-label="Top right radius" placeholder="0" defaultValue={0} />
              </HStack>
              <CollapsibleContent xstyle={styles.content}>
                <HStack gap={2}>
                  <Input aria-label="Bottom left radius" placeholder="0" defaultValue={0} />
                  <Input aria-label="Bottom right radius" placeholder="0" defaultValue={0} />
                </HStack>
              </CollapsibleContent>
            </VStack>
            <CollapsibleTrigger
              render={
                <Button
                  variant="outline"
                  size="icon"
                  aria-label={open ? "Fewer options" : "More options"}
                />
              }
            >
              {open ? <ArrowsInIcon aria-hidden="true" /> : <ArrowsOutIcon aria-hidden="true" />}
            </CollapsibleTrigger>
          </HStack>
        </Collapsible>
      </CardContent>
    </Card>
  )
}

File tree

A collapsible inside another one makes a file tree. collapsibleStyles.chevronInline turns a right-pointing chevron down.

Explorer
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  collapsibleStyles,
} from "@/components/ui/collapsible"
import { VStack } from "@/components/ui/stack"
import { color, space } from "@/theme/tokens.stylex"
import { CaretRightIcon } from "@phosphor-icons/react/dist/csr/CaretRight"
import { FileIcon } from "@phosphor-icons/react/dist/csr/File"
import { FolderIcon } from "@phosphor-icons/react/dist/csr/Folder"

const styles = stylex.create({
  card: { width: "100%", maxWidth: "16rem" },
  row: { width: "100%", justifyContent: "flex-start" },
  file: { color: color.foreground },
  children: { marginBlockStart: space.s1, marginInlineStart: space.s5 },
})

type FileTreeItem = { name: string; items?: FileTreeItem[] }

const fileTree: FileTreeItem[] = [
  {
    name: "components",
    items: [
      {
        name: "ui",
        items: [{ name: "button.tsx" }, { name: "card.tsx" }, { name: "input.tsx" }],
      },
      { name: "site-header.tsx" },
      { name: "docs-sidebar.tsx" },
    ],
  },
  {
    name: "lib",
    items: [{ name: "state-styles.ts" }, { name: "field-state.ts" }],
  },
  {
    name: "theme",
    items: [{ name: "tokens.stylex.ts" }, { name: "markers.stylex.ts" }],
  },
  { name: "app.tsx" },
  { name: "router.tsx" },
  { name: "package.json" },
]

function TreeItem({ item }: { item: FileTreeItem }) {
  if (item.items) {
    return (
      <Collapsible>
        <CollapsibleTrigger render={<Button variant="ghost" size="sm" xstyle={styles.row} />}>
          <CaretRightIcon aria-hidden="true" {...stylex.props(collapsibleStyles.chevronInline)} />
          <FolderIcon aria-hidden="true" />
          {item.name}
        </CollapsibleTrigger>
        <CollapsibleContent xstyle={styles.children}>
          <VStack gap={1}>
            {item.items.map((child) => (
              <TreeItem key={child.name} item={child} />
            ))}
          </VStack>
        </CollapsibleContent>
      </Collapsible>
    )
  }
  return (
    <Button variant="link" size="sm" xstyle={[styles.row, styles.file]}>
      <FileIcon aria-hidden="true" />
      {item.name}
    </Button>
  )
}

export default function CollapsibleFileTree() {
  return (
    <Card size="sm" xstyle={styles.card}>
      <CardHeader>
        <CardTitle>Explorer</CardTitle>
      </CardHeader>
      <CardContent>
        <VStack gap={1}>
          {fileTree.map((item) => (
            <TreeItem key={item.name} item={item} />
          ))}
        </VStack>
      </CardContent>
    </Card>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Collapsible part of the same name and accepts its props. See the Base UI reference for the full list. Each part also takes xstyle and className. CollapsibleTrigger and CollapsibleContent take style as real inline CSS, merged over the compiled styles.

Collapsible

PropTypeDefault
openboolean—
defaultOpenbooleanfalse
onOpenChange(open: boolean, details) => void—
disabledbooleanfalse

CollapsibleContent

PropTypeDefault
keepMountedbooleanfalse
hiddenUntilFoundbooleanfalse

hiddenUntilFound hides the closed panel with hidden="until-found" instead of unmounting it, which lets the browser's find-in-page reach the text and open the panel. It overrides keepMounted.

CollapsibleContent applies xstyle and className to the inner element and style to the panel. The panel animates its height between 0 and the measured content height, and a padded box of height 0 still draws its padding.

collapsibleStyles

Styles for an icon inside the trigger. Each reads the open state from the trigger and has its own transition.

KeyWhat it is
chevronTurns a down-pointing chevron up when the panel opens
chevronInlineTurns a right-pointing chevron down when the panel opens

Data attributes

AttributeOnEffect
data-slot="collapsible-content"the panelTargets the animated panel
data-starting-style, data-ending-stylethe panelBase UI writes them while the panel animates
data-open, data-disabledroot, trigger, panelBase UI writes them
data-panel-openthe triggerBase UI writes it

CSS variables

VariableOnEffect
--collapsible-panel-heightthe panelBase UI writes the measured height; the panel transitions to it
--arene-collapsible-openthe trigger0 closed, 1 open. Inherited, so anything inside the trigger can read it