# Collapsible Documentation

Conceals or reveals content sections.

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

Copy Page

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
</script>
<Collapsible.Root class="w-[327px] space-y-3">
  <div class="flex items-center justify-between space-x-10">
    <h4 class="text-[15px] font-medium">@huntabyte starred 3 repositories</h4>
    <Collapsible.Trigger
      class="rounded-9px border-border-input bg-background-alt text-foreground shadow-btn hover:bg-muted inline-flex h-10 w-10 items-center justify-center border transition-all active:scale-[0.98]"
      aria-label="Show starred repositories"
    >
      <CaretUpDown class="size-4" weight="bold" />
    </Collapsible.Trigger>
  </div>
  <Collapsible.Content
    hiddenUntilFound
    class="data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up space-y-2 overflow-hidden font-mono text-[15px] tracking-[0.01em]"
  >
    <div
      class="rounded-9px bg-muted inline-flex h-12 w-full items-center px-[18px] py-3"
    >
      @huntabyte/bits-ui
    </div>
    <div
      class="rounded-9px bg-muted inline-flex h-12 w-full items-center px-[18px] py-3"
    >
      @huntabyte/shadcn-svelte
    </div>
    <div
      class="rounded-9px bg-muted inline-flex h-12 w-full items-center px-[18px] py-3"
    >
      @svecosystem/runed
    </div>
  </Collapsible.Content>
</Collapsible.Root>
```

## Overview

The Collapsible component enables you to create expandable and collapsible content sections. It provides an efficient way to manage space and organize information in user interfaces, enabling users to show or hide content as needed.

## Key Features

- **Accessibility**: ARIA attributes for screen reader compatibility and keyboard navigation.  
- **Transition Support**: CSS variables and data attributes for smooth transitions between states.  
- **Flexible State Management**: Supports controlled and uncontrolled state, take control if needed.  
- **Compound Component Structure**: Provides a set of sub-components that work together to create a fully-featured collapsible.  
- **Hidden Until Found**: Support for the `hidden="until-found"` attribute for browser search integration.

## Architecture

The Collapsible component is composed of a few sub-components, each with a specific role:

- **Root**: The parent container that manages the state and context for the collapsible functionality.  
- **Trigger**: The interactive element (e.g., button) that toggles the expanded/collapsed state of the content.  
- **Content**: The container for the content that will be shown or hidden based on the collapsible state. ## Structure

Here's an overview of how the Collapsible component is structured in code:

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
</script>
<Collapsible.Root>
  <Collapsible.Trigger />
  <Collapsible.Content />
</Collapsible.Root>
```

## Reusable Components

It's recommended to use the `Collapsible` primitives to create your own custom collapsible component that can be used throughout your application.

MyCollapsible.svelte

```svelte
<script lang="ts">
  import { Collapsible, type WithoutChild } from "bits-ui";
  type Props = WithoutChild<Collapsible.RootProps> & {
    buttonText: string;
  };
  let {
    open = $bindable(false),
    ref = $bindable(null),
    buttonText,
    children,
    ...restProps
  }: Props = $props();
</script>
<Collapsible.Root bind:open bind:ref {...restProps}>
  <Collapsible.Trigger>{buttonText}</Collapsible.Trigger>
  <Collapsible.Content>
    {@render children?.()}
  </Collapsible.Content>
</Collapsible.Root>
```

You can then use the `MyCollapsible` component in your application like so:

+page.svelte

```svelte
<script lang="ts">
  import MyCollapsible from "$lib/components/MyCollapsible.svelte";
</script>
<MyCollapsible buttonText="Open Collapsible"
  >Here is my collapsible content.</MyCollapsible
>
```

## Managing Open State

This section covers how to manage the `open` state of the Collapsible.

### Two-Way Binding

Use `bind:open` for simple, automatic state synchronization:

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
  let isOpen = $state(false);
</script>
<button onclick={() => (isOpen = true)}>Open Collapsible</button>
<Collapsible.Root bind:open={isOpen}>
</Collapsible.Root>
```

### Fully Controlled

Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes.

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
  let myOpen = $state(false);
  function getOpen() {
    return myOpen;
  }
  function setOpen(newOpen: boolean) {
    myOpen = newOpen;
  }
</script>
<Collapsible.Root bind:open={getOpen, setOpen}>
</Collapsible.Root>
```

## Svelte Transitions

The Collapsible component can be enhanced with Svelte's built-in transition effects or other animation libraries.

### Using `forceMount` and `child` Snippets

To apply Svelte transitions to Collapsible components, use the `forceMount` prop in combination with the `child` snippet. This approach gives you full control over the mounting behavior and animation of the `Collapsible.Content`.

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
  import { fade } from "svelte/transition";
</script>
<Collapsible.Root>
  <Collapsible.Trigger>Open</Collapsible.Trigger>
  <Collapsible.Content forceMount>
    {#snippet child({ props, open })}
      {#if open}
        <div {...props} transition:fade>
        </div>
      {/if}
    {/snippet}
  </Collapsible.Content>
</Collapsible.Root>
```

In this example:

- The `forceMount` prop ensures the content is always in the DOM.
- The `child` snippet provides access to the open state and component props.
- Svelte's `#if` block controls when the content is visible.
- Transition directive ( `transition:fade` ) apply the animations.

### Best Practices

For cleaner code and better maintainability, consider creating custom reusable components that encapsulate this transition logic.

MyCollapsibleContent.svelte

```svelte
<script lang="ts">
  import { Collapsible, type WithoutChildrenOrChild } from "bits-ui";
  import { fade } from "svelte/transition";
  import type { Snippet } from "svelte";
  let {
    ref = $bindable(null),
    duration = 200,
    children,
    ...restProps
  }: WithoutChildrenOrChild<Collapsible.ContentProps> & {
    duration?: number;
    children?: Snippet;
  } = $props();
</script>
<Collapsible.Content forceMount bind:ref {...restProps}>
  {#snippet child({ props, open })}
    {#if open}
      <div {...props} transition:fade={{ duration }}>
        {@render children?.()}
      </div>
    {/if}
  {/snippet}
</Collapsible.Content>
```

You can then use the `MyCollapsibleContent` component alongside the other `Collapsible` primitives throughout your application:

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
  import { MyCollapsibleContent } from "$lib/components";
</script>
<Collapsible.Root>
  <Collapsible.Trigger>Open</Collapsible.Trigger>
  <MyCollapsibleContent duration={300}>
  </MyCollapsibleContent>
</Collapsible.Root>
```

## Hidden Until Found

The `hiddenUntilFound` prop enables integration with the browser's find-in-page functionality. When enabled, the collapsible content is marked with `hidden="until-found"`, which allows browsers to automatically expand collapsed content when users search for text within it.

Expand Code

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
</script>
<div class="flex w-full max-w-md flex-col gap-4">
  <div
    class="border-border bg-background-alt absolute left-4 top-4 flex flex-col gap-2 rounded-xl border p-4"
  >
    <div class="text-foreground-alt flex flex-col gap-2 text-sm">
      <span>Try searching for "searchable content" on this page</span>
      <code class="bg-muted w-fit rounded px-1 py-0.5 text-xs"
        >(Ctrl+F / Cmd+F)</code
      >
    </div>
  </div>
  <Collapsible.Root class="flex flex-col gap-3">
    <div class="flex items-center justify-between gap-4">
      <h4 class="text-[15px] font-medium">FAQ: How does search work?</h4>
      <Collapsible.Trigger
        class="rounded-9px border-border-input bg-background-alt text-foreground shadow-btn hover:bg-muted inline-flex h-10 w-10 items-center justify-center border transition-all active:scale-[0.98]"
        aria-label="Toggle FAQ answer"
      >
        <CaretUpDown class="size-4" weight="bold" />
      </Collapsible.Trigger>
    </div>
    <Collapsible.Content
      hiddenUntilFound
      class="data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up overflow-hidden"
    >
      <div
        class="bg-background border-border rounded-lg border p-4 text-[14px] leading-relaxed"
      >
        <p class="mb-3">
          This collapsible contains <strong>searchable content</strong> that
          demonstrates the
          <code class="bg-muted rounded px-1 py-0.5 text-xs"
            >hiddenUntilFound</code
          > feature. When you search for text within this collapsed section, the
          browser will automatically expand it to show the matching results.
        </p>
      </div>
    </Collapsible.Content>
  </Collapsible.Root>
</div>
```

### Basic Usage

```svelte
<script lang="ts">
  import { Collapsible } from "bits-ui";
</script>
<Collapsible.Root>
  <Collapsible.Trigger>Show More Details</Collapsible.Trigger>
  <Collapsible.Content hiddenUntilFound={true}>
    <p>
      This content will be automatically revealed when users search for text
      within it using Ctrl+F (Cmd+F on Mac).
    </p>
    <p>
      For example, try searching for "automatically revealed" on this page.
    </p>
  </Collapsible.Content>
</Collapsible.Root>
```

## API Reference

### Collapsible.Root

The root collapsible container which manages the state of the collapsible.

| Property                                                                                     | Type                                                                                                                                                                                                                                                            | Description                                                                                                                                                 | Details                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` $bindable | `boolean`                                                                                                                                                                                                                                      | The open state of the collapsible. The content will be visible when this is true, and hidden when it's false.`Default: false`                 |                                      |
| `onOpenChange`                                             | `function`- (open: boolean) =\&gt; void                                                 | A callback function called when the open state changes.`Default:  undefined`                                                               |                                      |
| `onOpenChangeComplete`                                     | `function`- (open: boolean) =\&gt; void                                                 | A callback function called after the open state changes and all animations have completed.`Default:  undefined`                            |                                      |
| `disabled`                                                 | `boolean`                                                                                                                                                                                                                                      | Whether or not the collapsible is disabled. This prevents the user from interacting with it.`Default: false`                                  |                                      |
| `ref` $bindable                               | `HTMLDivElement`                                                                                                                                                                                                                               | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null`                             |                                      |
| `children`                                                 | `Snippet`                                                                                                                                                                                                                                      | The children content to render.`Default:  undefined`                                                                                       |                                      |
| `child`                                                    | `Snippet`- type SnippetProps = \&#123; props: Record\&lt;string, unknown\&gt;; \&#125;; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` |  | | Data Attribute                     | Value                                                                                                                                                                                              | Description                                      | Details                                                                                                                                                                                      |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The collapsible's open state.             |                                      |
| `data-disabled`                           | `''`                                                                                                                                                                              | Present when the collapsible is disabled. |                                      |
| `data-collapsible-root`                   | `''`                                                                                                                                                                              | Present on the root element.              |  |

### Collapsible.Trigger

The button responsible for toggling the collapsible's open state.

| Property                                                                                    | Type                                                                                                                                                                                                                                                            | Description                                                                                                                                                 | Details                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` $bindable | `HTMLButtonElement`                                                                                                                                                                                                                            | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null`                             |                                      |
| `children`                                                | `Snippet`                                                                                                                                                                                                                                      | The children content to render.`Default:  undefined`                                                                                       |                                      |
| `child`                                                   | `Snippet`- type SnippetProps = \&#123; props: Record\&lt;string, unknown\&gt;; \&#125;; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` |  | | Data Attribute                     | Value                                                                                                                                                                                              | Description                                                      | Details                                                                                                                                                                                        |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The collapsible's open state.                             |                                        |
| `data-disabled`                           | `''`                                                                                                                                                                              | Present when the collapsible or this trigger is disabled. |                                       |
| `data-collapsible-trigger`                | `''`                                                                                                                                                                              | Present on the trigger element.                           |  |

### Collapsible.Content

The content displayed when the collapsible is open.

| Property                                                                    | Type                                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                          | Details                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forceMount` | `boolean`                                                                                                                                                                                                                                                       | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false`                     |                                      |
| `hiddenUntilFound`                        | `boolean`                                                                                                                                                                                                                                                       | When true, the content will be marked with `hidden="until-found"` when collapsed, allowing browsers to find and automatically expand the content during page searches.`Default: false` |                                      |
| `ref` $bindable              | `HTMLDivElement`                                                                                                                                                                                                                                                | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null`                                                                      |                                      |
| `children`                                | `Snippet`                                                                                                                                                                                                                                                       | The children content to render.`Default:  undefined`                                                                                                                                |                                      |
| `child`                                   | `Snippet`- type SnippetProps = \&#123; open: boolean; props: Record\&lt;string, unknown\&gt;; \&#125;; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                                          |  | | Data Attribute                     | Value                                                                                                                                                                                                | Description                                      | Details                                                                                                                                                                                        |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-state` | `enum`- 'open' \| 'closed' | The collapsible's open state.             |                                      |
| `data-disabled`                           | `''`                                                                                                                                                                                | Present when the collapsible is disabled. |                                      |
| `data-collapsible-content`                | `''`                                                                                                                                                                                | Present on the content element.           |  |

| CSS Variable                                              | Description                                                           | Details                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bits-collapsible-content-height` | The height of the collapsible content element. |                                      |
| `--bits-collapsible-content-width`                               | The width of the collapsible content element.  |  |

[Previous Checkbox](/docs/components/checkbox)

[Next Combobox](/docs/components/combobox)