# Collapsible

URL: https://ark-ui.com/docs/components/collapsible
LLM: https://ark-ui.com/llms.txt/components/collapsible

An interactive component that can be expanded or collapsed.

---



## Anatomy



```tsx
<Collapsible.Root>
  <Collapsible.Trigger>
    <Collapsible.Indicator />
  </Collapsible.Trigger>
  <Collapsible.Content />
</Collapsible.Root>
```

## Examples

```tsx
import { Collapsible } from '@ark-ui/react/collapsible'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/collapsible.module.css'

export const Basic = () => (
  <Collapsible.Root className={styles.Root}>
    <Collapsible.Trigger className={styles.Trigger}>
      What is Ark UI?
      <Collapsible.Indicator className={styles.Indicator}>
        <ChevronRightIcon />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content className={styles.Content}>
      <div className={styles.Body}>
        Ark UI is a headless component library for building accessible, high-quality UI components for React, Solid,
        Vue, and Svelte.
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
)
```

### Disabled

Use the `disabled` prop to disable the collapsible and prevent it from being toggled.

```tsx
import { Collapsible } from '@ark-ui/react/collapsible'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/collapsible.module.css'

export const Disabled = () => (
  <Collapsible.Root className={styles.Root} disabled>
    <Collapsible.Trigger className={styles.Trigger}>
      System Requirements
      <Collapsible.Indicator className={styles.Indicator}>
        <ChevronRightIcon />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content className={styles.Content}>
      <div className={styles.Body}>This section is currently unavailable.</div>
    </Collapsible.Content>
  </Collapsible.Root>
)
```

### Partial Collapse

Use the `collapsedHeight` or `collapsedWidth` props to create a "show more/less" pattern. When set, the content
maintains the specified dimensions when collapsed instead of collapsing to 0px.

We expose the `--collapsed-height` or `--collapsed-width` variables to use in your CSS animations.

```tsx
import { Collapsible } from '@ark-ui/react/collapsible'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/collapsible.module.css'

export const PartialCollapse = () => (
  <Collapsible.Root className={styles.Root} collapsedHeight="100px">
    <Collapsible.Trigger className={styles.Trigger}>
      Read More
      <Collapsible.Indicator className={styles.Indicator}>
        <ChevronRightIcon />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content className={styles.Content}>
      <div className={styles.Body}>
        <p>
          Ark UI is a headless component library for building accessible, high-quality UI components for React, Solid,
          Vue, and Svelte. It provides unstyled, fully accessible components that you can customize to match your design
          system.
        </p>
        <p>
          Built on top of Zag.js state machines, Ark UI ensures consistent behavior across all frameworks while giving
          you complete control over styling. Each component follows WAI-ARIA patterns for accessibility out of the box.
        </p>
        <p>
          Whether you're building a design system from scratch or need reliable primitives for your next project, Ark UI
          provides the foundation you need without imposing any visual constraints.
        </p>
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
)
```

> Interactive elements (links, buttons, inputs) within the collapsed area automatically become `inert` to prevent
> keyboard navigation to hidden content.

### Nested Collapsibles

You can nest collapsibles within collapsibles to create hierarchical content structures.

```tsx
import { Collapsible } from '@ark-ui/react/collapsible'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/collapsible.module.css'

export const Nested = () => (
  <Collapsible.Root className={styles.Root}>
    <Collapsible.Trigger className={styles.Trigger}>
      Getting Started
      <Collapsible.Indicator className={styles.Indicator}>
        <ChevronRightIcon />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content className={styles.Content}>
      <div className={styles.Body}>
        <p>Welcome to the Ark UI documentation. Here are some topics to explore:</p>

        <Collapsible.Root className={styles.Nested}>
          <Collapsible.Trigger className={styles.Trigger}>
            Installation
            <Collapsible.Indicator className={styles.Indicator}>
              <ChevronRightIcon />
            </Collapsible.Indicator>
          </Collapsible.Trigger>
          <Collapsible.Content className={styles.Content}>
            <div className={styles.Body}>
              <p>Install Ark UI using your preferred package manager:</p>
              <code>npm install @ark-ui/react</code>
            </div>
          </Collapsible.Content>
        </Collapsible.Root>

        <Collapsible.Root className={styles.Nested}>
          <Collapsible.Trigger className={styles.Trigger}>
            Styling
            <Collapsible.Indicator className={styles.Indicator}>
              <ChevronRightIcon />
            </Collapsible.Indicator>
          </Collapsible.Trigger>
          <Collapsible.Content className={styles.Content}>
            <div className={styles.Body}>
              <p>Ark UI components are unstyled by default. Use CSS modules, Tailwind, or any styling solution.</p>
            </div>
          </Collapsible.Content>
        </Collapsible.Root>
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
)
```

### Lazy Mount

Use `lazyMount` to delay mounting the content until first opened, and `unmountOnExit` to remove it from the DOM when
collapsed. Combining both ensures the component is only in the DOM while expanded.

```tsx
import { Collapsible } from '@ark-ui/react/collapsible'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/collapsible.module.css'

export const LazyMount = () => (
  <Collapsible.Root className={styles.Root} lazyMount unmountOnExit>
    <Collapsible.Trigger className={styles.Trigger}>
      Session Details
      <Collapsible.Indicator className={styles.Indicator}>
        <ChevronRightIcon />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content className={styles.Content}>
      <div className={styles.Body}>
        This content is lazily mounted when first opened and removed from the DOM when collapsed.
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
)
```

### Root Provider

An alternative way to control the collapsible is to use the `RootProvider` component and the `useCollapsible` hook. This
way you can access the state and methods from outside the component.

```tsx
import { Collapsible, useCollapsible } from '@ark-ui/react/collapsible'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/collapsible.module.css'

export const RootProvider = () => {
  const collapsible = useCollapsible()

  return (
    <div className="stack">
      <output>
        collapsible: {String(collapsible.open)}, visible: {String(collapsible.visible)}
      </output>
      <Collapsible.RootProvider className={styles.Root} value={collapsible}>
        <Collapsible.Trigger className={styles.Trigger}>
          Toggle Panel
          <Collapsible.Indicator className={styles.Indicator}>
            <ChevronRightIcon />
          </Collapsible.Indicator>
        </Collapsible.Trigger>
        <Collapsible.Content className={styles.Content}>
          <div className={styles.Body}>
            This panel can be toggled by the button above, which uses the useCollapsible hook for state management.
          </div>
        </Collapsible.Content>
      </Collapsible.RootProvider>
    </div>
  )
}
```

## Guides

### Indicator Animation

To rotate the indicator icon (such as a chevron) when the collapsible opens and closes, use CSS transforms with the
`data-state` attribute:

```css
[data-scope='collapsible'][data-part='indicator'] {
  transition: transform 200ms;

  &[data-state='open'] {
    transform: rotate(180deg);
  }
}
```

### Open vs Visible

When using `useCollapsible` or `useCollapsibleContext`, you can access the `open` and `visible` state properties. They
seem similar but serve different purposes:

- **`open`**: Indicates the intended state of the collapsible. This is `true` when the collapsible should be expanded
  and `false` when it should be collapsed. This changes immediately when triggered.

- **`visible`**: Indicates whether the content is currently visible in the DOM. This accounts for exit animations - the
  content remains `visible` while the closing animation plays, even though `open` is already `false`. Once the animation
  completes, `visible` becomes `false`.

### Content Animation

Use the `--height` and/or `--width` CSS variables to animate the size of the content when it expands or closes.

If you use `collapsedHeight` or `collapsedWidth`, update your CSS animations to use the `--collapsed-height` or
`--collapsed-width` variables as the starting/ending point:

```css
@keyframes expand {
  from {
    height: var(--collapsed-height, 0);
  }
  to {
    height: var(--height);
  }
}

@keyframes collapse {
  from {
    height: var(--height);
  }
  to {
    height: var(--collapsed-height, 0);
  }
}

[data-scope='collapsible'][data-part='content'] {
  &[data-state='open'] {
    animation: expand 250ms;
  }
  &[data-state='closed'] {
    animation: collapse 250ms;
  }
}
```

## API Reference

### Props

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`collapsedHeight`**
Type: `string | number`
Required: false
Default Value: `undefined`
Description: The height of the content when collapsed.

**`collapsedWidth`**
Type: `string | number`
Required: false
Default Value: `undefined`
Description: The width of the content when collapsed.

**`defaultOpen`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: The initial open state of the collapsible when rendered.
Use when you don't need to control the open state of the collapsible.

**`disabled`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the collapsible is disabled.

**`hideMode`**
Type: `HideMode`
Required: false
Default Value: `'display-none'`
Description: How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 `<Activity mode="hidden">`. Effects pause. Requires React 19+.

**`ids`**
Type: `Partial<{ root: string; content: string; trigger: string }>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the collapsible. Useful for composition.

**`lazyMount`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to enable lazy mounting

**`onExitComplete`**
Type: `VoidFunction`
Required: false
Default Value: `undefined`
Description: The callback invoked when the exit animation completes.

**`onOpenChange`**
Type: `(details: OpenChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: The callback invoked when the open state changes.

**`open`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: The controlled open state of the collapsible.

**`unmountOnExit`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to unmount on exit.

#### Data Attributes

**`data-scope`**: collapsible
**`data-part`**: root
**`data-state`**: "open" | "closed"

### Content

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: collapsible
**`data-part`**: content
**`data-collapsible`**: 
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled
**`data-has-collapsed-size`**: Present when the content has collapsed width or height

### Indicator

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: collapsible
**`data-part`**: indicator
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled

### RootProvider

#### Props

**`value`**
Type: `UseCollapsibleReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Trigger

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: collapsible
**`data-part`**: trigger
**`data-state`**: "open" | "closed"
**`data-disabled`**: Present when disabled

### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `open` | `boolean` | Whether the collapsible is open. |
| `visible` | `boolean` | Whether the collapsible is visible (open or closing) |
| `disabled` | `boolean` | Whether the collapsible is disabled |
| `setOpen` | `(open: boolean) => void` | Function to open or close the collapsible. |
| `measureSize` | `VoidFunction` | Function to measure the size of the content. |


## Accessibility

### Keyboard Support

**`Space`**
Description: Opens/closes the collapsible.

**`Enter`**
Description: Opens/closes the collapsible.