# Collapsible

URL: https://ark-ui.com/docs/components/collapsible
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/collapsible.mdx

An interactive component that can be expanded or collapsed.

---

<ComponentPreview id="Collapsible" />

## Anatomy

<Anatomy id="collapsible" />

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

## Examples

**Example: basic**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component Basic() {
  <Collapsible.Root class={styles.Root}>
    <Collapsible.Trigger class={styles.Trigger}>
      {'What is Ark UI?'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={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.

**Example: disabled**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component Disabled() {
  <Collapsible.Root class={styles.Root} disabled>
    <Collapsible.Trigger class={styles.Trigger}>
      {'System Requirements'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={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.

**Example: partial-collapse**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component PartialCollapse() {
  <Collapsible.Root class={styles.Root} collapsedHeight="100px">
    <Collapsible.Trigger class={styles.Trigger}>
      {'Read More'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={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.

**Example: nested**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

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

        <Collapsible.Root class={styles.Nested}>
          <Collapsible.Trigger class={styles.Trigger}>
            {'Installation'}
            <Collapsible.Indicator class={styles.Indicator}>
              <ChevronRight />
            </Collapsible.Indicator>
          </Collapsible.Trigger>
          <Collapsible.Content class={styles.Content}>
            <div class={styles.Body}>
              <p>{'Install Ark UI using your preferred package manager:'}</p>
              <code>{'npm install ark-ripple'}</code>
            </div>
          </Collapsible.Content>
        </Collapsible.Root>

        <Collapsible.Root class={styles.Nested}>
          <Collapsible.Trigger class={styles.Trigger}>
            {'Styling'}
            <Collapsible.Indicator class={styles.Indicator}>
              <ChevronRight />
            </Collapsible.Indicator>
          </Collapsible.Trigger>
          <Collapsible.Content class={styles.Content}>
            <div class={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.

**Example: lazy-mount**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component LazyMount() {
  <Collapsible.Root class={styles.Root} lazyMount unmountOnExit>
    <Collapsible.Trigger class={styles.Trigger}>
      {'Session Details'}
      <Collapsible.Indicator class={styles.Indicator}>
        <ChevronRight />
      </Collapsible.Indicator>
    </Collapsible.Trigger>
    <Collapsible.Content class={styles.Content}>
      <div class={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.

**Example: root-provider**

```ripple
import { Collapsible } from 'ark-ripple/collapsible';
import { useCollapsible } from 'ark-ripple/collapsible';
import { ChevronRight } from 'lucide-ripple';
import styles from 'styles/collapsible.module.css';

export component RootProvider() {
  const collapsible = useCollapsible();

  <div class="stack">
    <output>
      {'collapsible: '}
      {String(@collapsible.open)}
      {', visible: '}
      {String(@collapsible.visible)}
    </output>
    <Collapsible.RootProvider class={styles.Root} value={collapsible}>
      <Collapsible.Trigger class={styles.Trigger}>
        {'Toggle Panel'}
        <Collapsible.Indicator class={styles.Indicator}>
          <ChevronRight />
        </Collapsible.Indicator>
      </Collapsible.Trigger>
      <Collapsible.Content class={styles.Content}>
        <div class={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

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `collapsedHeight` | `string | number` | No | The height of the content when collapsed. |
| `collapsedWidth` | `string | number` | No | The width of the content when collapsed. |
| `defaultOpen` | `boolean` | No | The initial open state of the collapsible when rendered.
Use when you don't need to control the open state of the collapsible. |
| `disabled` | `boolean` | No | Whether the collapsible is disabled. |
| `ids` | `Partial<{ root: string; content: string; trigger: string }>` | No | The ids of the elements in the collapsible. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | The callback invoked when the exit animation completes. |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | The callback invoked when the open state changes. |
| `open` | `boolean` | No | The controlled open state of the collapsible. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | collapsible |
| `[data-part]` | root |
| `[data-state]` | "open" | "closed" |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--height` | The height of the element |
| `--width` | The width of the element |
| `--collapsed-height` | The height of the Content |
| `--collapsed-width` | The width of the Content |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | collapsible |
| `[data-part]` | indicator |
| `[data-state]` | "open" | "closed" |
| `[data-disabled]` | Present when disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCollapsibleReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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

<KeyBindingsTable id="collapsible" />