---
title: Collapsible
subtitle: A collapsible panel controlled by a button.
description: A high-quality, unstyled React collapsible component that displays a panel controlled by a button.
---

> FineSoft Components documentation. Independent Stencil port; not the official Base UI website.
>
> React API text and `@base-ui/react` examples are upstream references. FineSoft Stencil examples use `finesoft-components`. Do not treat the two packages as interchangeable.

# Collapsible

A high-quality, unstyled React collapsible component that displays a panel controlled by a button.

## Demo

### Tailwind

This example shows how to implement the component using Tailwind CSS.

```tsx
/* docs-comparison.tsx */
import ReactCollapsible from './react-collapsible';
import StencilCollapsible from './stencil-collapsible';
import { StencilComparison } from 'docs/src/components/StencilComparison';

export default function ExampleCollapsible() {
  return <StencilComparison component="collapsible" react={<ReactCollapsible />} stencil={<StencilCollapsible />} />;
}
```

```tsx
/* react-collapsible.tsx */
import * as React from 'react';
import { Collapsible } from '@base-ui/react/collapsible';

export default function ExampleCollapsible() {
  return (
    <Collapsible.Root className="flex min-h-36 w-48 flex-col justify-center text-neutral-950 dark:text-white">
      <Collapsible.Trigger className="group flex h-8 items-center justify-between gap-2 rounded-none border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 pl-3 pr-2 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400">
        Recovery keys
        <CaretRightIcon className="transition-transform duration-100 ease-[ease-out] group-data-panel-open:rotate-90" />
      </Collapsible.Trigger>
      <Collapsible.Panel className="flex h-[var(--collapsible-panel-height)] flex-col justify-end overflow-hidden text-sm transition-[height] duration-150 ease-[ease-out] [&[hidden]:not([hidden='until-found'])]:hidden data-ending-style:h-0 data-starting-style:h-0">
        <div className="flex flex-col gap-2 px-3.5 py-2">
          <div>alien-bean-pasta</div>
          <div>wild-irish-burrito</div>
          <div>horse-battery-staple</div>
        </div>
      </Collapsible.Panel>
    </Collapsible.Root>
  );
}

export function CaretRightIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="M6 12V4l4.5 4z" />
    </svg>
  );
}
```

```tsx
/* stencil-collapsible.tsx */
import type * as React from 'react';

export default function StencilCollapsible() {
  return (
    <fs-collapsible-root className="[&::part(collapsible)]:box-border [&::part(collapsible)]:border-0 [&::part(collapsible)]:border-solid [&::part(collapsible)]:flex [&::part(collapsible)]:min-h-36 [&::part(collapsible)]:w-48 [&::part(collapsible)]:flex-col [&::part(collapsible)]:justify-center [&::part(collapsible)]:text-neutral-950 dark:[&::part(collapsible)]:text-white">
      <fs-collapsible-trigger className="group [&::part(trigger)]:box-border [&::part(trigger)]:m-0 [&::part(trigger)]:py-0 [&::part(trigger)]:border-solid [&::part(trigger)]:[font-family:inherit] [&::part(trigger)]:flex [&::part(trigger)]:h-8 [&::part(trigger)]:items-center [&::part(trigger)]:justify-between [&::part(trigger)]:gap-2 [&::part(trigger)]:rounded-none [&::part(trigger)]:border [&::part(trigger)]:border-neutral-950 dark:[&::part(trigger)]:border-white [&::part(trigger)]:bg-white dark:[&::part(trigger)]:bg-neutral-950 [&::part(trigger)]:pl-3 [&::part(trigger)]:pr-2 [&::part(trigger)]:text-sm [&::part(trigger)]:leading-none [&::part(trigger)]:whitespace-nowrap [&::part(trigger)]:font-normal [&::part(trigger)]:text-neutral-950 dark:[&::part(trigger)]:text-white [&::part(trigger)]:select-none [&:not([data-disabled])::part(trigger)]:hover:bg-neutral-100 dark:[&:not([data-disabled])::part(trigger)]:hover:bg-neutral-800 [&:not([data-disabled])::part(trigger)]:active:bg-neutral-200 dark:[&:not([data-disabled])::part(trigger)]:active:bg-neutral-700 [&::part(trigger):focus-visible]:outline-2 [&::part(trigger):focus-visible]:-outline-offset-1 [&::part(trigger):focus-visible]:outline-neutral-950 dark:[&::part(trigger):focus-visible]:outline-white data-disabled:[&::part(trigger)]:border-neutral-500 data-disabled:[&::part(trigger)]:text-neutral-500 dark:data-disabled:[&::part(trigger)]:border-neutral-400 dark:data-disabled:[&::part(trigger)]:text-neutral-400">
        Recovery keys
        <CaretRightIcon className="transition-transform duration-100 ease-[ease-out] group-data-panel-open:rotate-90" />
      </fs-collapsible-trigger>
      <fs-collapsible-panel className="flex h-[var(--collapsible-panel-height)] flex-col justify-end overflow-hidden text-sm transition-[height] duration-150 ease-[ease-out] [&[hidden]:not([hidden='until-found'])]:hidden data-ending-style:h-0 data-starting-style:h-0">
        <div className="flex flex-col gap-2 px-3.5 py-2">
          <div>alien-bean-pasta</div>
          <div>wild-irish-burrito</div>
          <div>horse-battery-staple</div>
        </div>
      </fs-collapsible-panel>
    </fs-collapsible-root>
  );
}

export function CaretRightIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="M6 12V4l4.5 4z" />
    </svg>
  );
}
```

### CSS Modules

This example shows how to implement the component using CSS Modules.

```css
/* index.module.css */
.Collapsible {
  display: flex;
  width: 12rem;
  min-height: 9rem;
  flex-direction: column;
  justify-content: center;
  color: oklch(14.5% 0 0deg);

  @media (prefers-color-scheme: dark) {
    color: white;
  }
}

.Icon {
  transition: transform 100ms ease-out;
}

.Trigger {
  box-sizing: border-box;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 0.5rem;
  height: 2rem;
  padding: 0 0.5rem 0 0.75rem;
  margin: 0;
  border: 1px solid oklch(14.5% 0 0deg);
  border-radius: 0;
  background-color: white;
  color: oklch(14.5% 0 0deg);
  font-family: inherit;
  font-size: 0.875rem;
  font-weight: 400;
  line-height: 1;
  white-space: nowrap;
  -webkit-user-select: none;
  user-select: none;

  @media (prefers-color-scheme: dark) {
    border: 1px solid white;
    background-color: oklch(14.5% 0 0deg);
    color: white;
  }

  @media (hover: hover) {
    &:hover:not([data-disabled]) {
      background-color: oklch(97% 0 0deg);

      @media (prefers-color-scheme: dark) {
        background-color: oklch(26.9% 0 0deg);
      }
    }
  }

  &:active:not([data-disabled]) {
    background-color: oklch(92.2% 0 0deg);

    @media (prefers-color-scheme: dark) {
      background-color: oklch(37.1% 0 0deg);
    }
  }

  &:focus-visible {
    outline: 2px solid oklch(14.5% 0 0deg);
    outline-offset: -1px;

    @media (prefers-color-scheme: dark) {
      outline-color: white;
    }
  }

  &[data-panel-open] .Icon {
    transform: rotate(90deg);
  }

  &[data-disabled] {
    color: oklch(55.6% 0 0deg);
    border-color: oklch(55.6% 0 0deg);

    @media (prefers-color-scheme: dark) {
      color: oklch(70.8% 0 0deg);
      border-color: oklch(70.8% 0 0deg);
    }
  }
}

.Panel {
  display: flex;
  height: var(--collapsible-panel-height);
  flex-direction: column;
  justify-content: end;
  overflow: hidden;
  font-size: 0.875rem;
  line-height: 1.25rem;
  transition: height 150ms ease-out;

  &[hidden]:not([hidden='until-found']) {
    display: none;
  }

  &[data-starting-style],
  &[data-ending-style] {
    height: 0;
  }
}

.Content {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
  padding: 0.5rem 0.875rem;
}
```

```tsx
/* docs-comparison.tsx */
import ReactCollapsible from './react-collapsible';
import StencilCollapsible from './stencil-collapsible';
import { StencilComparison } from 'docs/src/components/StencilComparison';

export default function ExampleCollapsible() {
  return <StencilComparison component="collapsible" react={<ReactCollapsible />} stencil={<StencilCollapsible />} />;
}
```

```tsx
/* react-collapsible.tsx */
import * as React from 'react';
import { Collapsible } from '@base-ui/react/collapsible';
import styles from './index.module.css';

export default function ExampleCollapsible() {
  return (
    <Collapsible.Root className={styles.Collapsible}>
      <Collapsible.Trigger className={styles.Trigger}>
        Recovery keys
        <CaretRightIcon className={styles.Icon} />
      </Collapsible.Trigger>
      <Collapsible.Panel className={styles.Panel}>
        <div className={styles.Content}>
          <div>alien-bean-pasta</div>
          <div>wild-irish-burrito</div>
          <div>horse-battery-staple</div>
        </div>
      </Collapsible.Panel>
    </Collapsible.Root>
  );
}

export function CaretRightIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="M6 12V4l4.5 4z" />
    </svg>
  );
}
```

```tsx
/* stencil-collapsible.tsx */
import type * as React from 'react';
import './stencil.css';

export default function StencilCollapsible() {
  return (
    <fs-collapsible-root>
      <fs-collapsible-trigger>
        Recovery keys
        <CaretRightIcon />
      </fs-collapsible-trigger>
      <fs-collapsible-panel>
        <div className="demo-collapsible-hero-content">
          <div>alien-bean-pasta</div>
          <div>wild-irish-burrito</div>
          <div>horse-battery-staple</div>
        </div>
      </fs-collapsible-panel>
    </fs-collapsible-root>
  );
}

export function CaretRightIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="M6 12V4l4.5 4z" />
    </svg>
  );
}
```

```css
/* stencil.css */
/* Example layout and visual exceptions. Default component styles come from the theme. */
@layer fs-theme {
  .demo-collapsible-hero-content {
    display: flex;
    flex-direction: column;
    gap: var(--fs-space-2);
    padding: var(--fs-space-2) var(--fs-space-3-5);
  }
}
```

## Anatomy

Import the component and assemble its parts:

```jsx title="Anatomy"
import { Collapsible } from '@base-ui/react/collapsible';

<Collapsible.Root>
  <Collapsible.Trigger />
  <Collapsible.Panel />
</Collapsible.Root>;
```

## Stencil styling

The Stencil Root and Trigger use Shadow DOM. Their native elements are exposed as
`fs-collapsible-root::part(collapsible)` and `fs-collapsible-trigger::part(trigger)`.
The Panel remains a public Light DOM element: style `fs-collapsible-panel` directly
for height transitions, `hidden="until-found"`, and content layout.

Import the optional theme and select it on an ancestor. Default component styling
requires no classes:

```tsx title="Optional Stencil theme"
<div data-fs-theme="base-ui">
  <fs-collapsible-root>
    <fs-collapsible-trigger>Shipping details</fs-collapsible-trigger>
    <fs-collapsible-panel>Standard shipping takes 3–5 business days.</fs-collapsible-panel>
  </fs-collapsible-root>
</div>
```

Use `--fs-collapsible-*` variables to customize the theme, or `::part()` for a
custom skin. Classes stay on the public hosts. Root state and Trigger
`data-panel-open` / `data-disabled` remain available on those hosts for slotted
content such as icons. `data-fs-theme="none"` opts a subtree out of the theme.

## Examples

### Hidden until found

The `hiddenUntilFound` prop hides the closed panel with [`hidden="until-found"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) so the browser can search its contents with find-in-page—<kbd>Ctrl</kbd>+<kbd>F</kbd> (<kbd>Cmd</kbd>+<kbd>F</kbd> on macOS)—and reveal the panel when a match is found. The closed panel always remains mounted in the DOM, which also makes its contents indexable by search engines.

Older browsers that don't support `hidden="until-found"` keep the panel hidden until its trigger opens it, and find-in-page skips over the contents.

```tsx title="Searchable hidden panel"
<Collapsible.Root>
  <Collapsible.Trigger>Shipping details</Collapsible.Trigger>
  {/* @highlight-text "hiddenUntilFound" */}
  <Collapsible.Panel hiddenUntilFound>Standard shipping takes 3–5 business days.</Collapsible.Panel>
</Collapsible.Root>
```

See the [Accordion example](/react/components/accordion.md) for an interactive demo.

## API reference

### Root

Groups all parts of the collapsible.
Renders a `<div>` element.

**Root Props:**

| Prop         | Type                                                                                           | Default | Description                                                                                                                                                                                   |
| :----------- | :--------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultOpen  | `boolean`                                                                                      | `false` | Whether the collapsible panel is initially open. To render a controlled collapsible, use the `open` prop instead.                                                                             |
| open         | `boolean`                                                                                      | -       | Whether the collapsible panel is currently open. To render an uncontrolled collapsible, use the `defaultOpen` prop instead.                                                                   |
| onOpenChange | `((open: boolean, eventDetails: Collapsible.Root.ChangeEventDetails) => void)`                 | -       | Event handler called when the panel is opened or closed.                                                                                                                                      |
| disabled     | `boolean`                                                                                      | `false` | Whether the component should ignore user interaction.                                                                                                                                         |
| className    | `string \| ((state: Collapsible.Root.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style        | `React.CSSProperties \| ((state: Collapsible.Root.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render       | `ReactElement \| ((props: HTMLProps, state: Collapsible.Root.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Root Data Attributes:**

| Attribute           | Type | Description                                       |
| :------------------ | :--- | :------------------------------------------------ |
| data-open           | -    | Present when the collapsible is open.             |
| data-closed         | -    | Present when the collapsible is closed.           |
| data-starting-style | -    | Present when the collapsible begins animating in. |
| data-ending-style   | -    | Present when the collapsible is animating out.    |

### Root.Props

Re-export of [Root](/react/components/collapsible.md) props.

### Root.State

```typescript
type CollapsibleRootState = {
  /** Whether the collapsible panel is currently open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  transitionStatus: TransitionStatus;
};
```

### Root.ChangeEventReason

```typescript
type CollapsibleRootChangeEventReason = 'trigger-press' | 'none';
```

### Root.ChangeEventDetails

```typescript
type CollapsibleRootChangeEventDetails = ({ reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent } | { reason: 'none'; event: Event }) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};
```

### Trigger

A button that opens and closes the collapsible panel.
Renders a `<button>` element.

**Trigger Props:**

| Prop         | Type                                                                                              | Default | Description                                                                                                                                                                                   |
| :----------- | :------------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nativeButton | `boolean`                                                                                         | `true`  | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example, `<div>`).     |
| className    | `string \| ((state: Collapsible.Trigger.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style        | `React.CSSProperties \| ((state: Collapsible.Trigger.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render       | `ReactElement \| ((props: HTMLProps, state: Collapsible.Trigger.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Trigger Data Attributes:**

| Attribute       | Type | Description                                 |
| :-------------- | :--- | :------------------------------------------ |
| data-panel-open | -    | Present when the collapsible panel is open. |

### Trigger.Props

Re-export of [Trigger](/react/components/collapsible.md) props.

### Trigger.State

```typescript
type CollapsibleTriggerState = {
  /** Whether the collapsible panel is currently open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  transitionStatus: TransitionStatus;
};
```

### Panel

A panel with the collapsible contents.
Renders a `<div>` element.

**Panel Props:**

| Prop             | Type                                                                                            | Default | Description                                                                                                                                                                                                 |
| :--------------- | :---------------------------------------------------------------------------------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| hiddenUntilFound | `boolean`                                                                                       | `false` | Allows the browser's built-in page search to find and expand the panel contents. Overrides the `keepMounted` prop and uses `hidden="until-found"`&#xA;to hide the element without removing it from the DOM. |
| className        | `string \| ((state: Collapsible.Panel.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                                    |
| style            | `React.CSSProperties \| ((state: Collapsible.Panel.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                                 |
| keepMounted      | `boolean`                                                                                       | `false` | Whether to keep the element in the DOM while the panel is hidden.&#xA;This prop is ignored when `hiddenUntilFound` is used.                                                                                 |
| render           | `ReactElement \| ((props: HTMLProps, state: Collapsible.Panel.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.               |

**Panel Data Attributes:**

| Attribute           | Type | Description                                   |
| :------------------ | :--- | :-------------------------------------------- |
| data-open           | -    | Present when the collapsible panel is open.   |
| data-closed         | -    | Present when the collapsible panel is closed. |
| data-starting-style | -    | Present when the panel begins animating in.   |
| data-ending-style   | -    | Present when the panel is animating out.      |

**Panel CSS Variables:**

| Variable                     | Type     | Description                     |
| :--------------------------- | :------- | :------------------------------ |
| `--collapsible-panel-height` | `number` | The collapsible panel's height. |
| `--collapsible-panel-width`  | `number` | The collapsible panel's width.  |

### Panel.Props

Re-export of [Panel](/react/components/collapsible.md) props.

### Panel.State

```typescript
type CollapsiblePanelState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the collapsible panel is currently open. */
  open: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
};
```

## Export Groups

- `Collapsible.Root`: `Collapsible.Root`, `Collapsible.Root.State`, `Collapsible.Root.Props`, `Collapsible.Root.ChangeEventReason`, `Collapsible.Root.ChangeEventDetails`
- `Collapsible.Trigger`: `Collapsible.Trigger`, `Collapsible.Trigger.State`, `Collapsible.Trigger.Props`
- `Collapsible.Panel`: `Collapsible.Panel`, `Collapsible.Panel.State`, `Collapsible.Panel.Props`
- `Default`: `CollapsibleRootState`, `CollapsibleRootProps`, `CollapsibleRootChangeEventReason`, `CollapsibleRootChangeEventDetails`, `CollapsibleTriggerState`, `CollapsibleTriggerProps`, `CollapsiblePanelState`, `CollapsiblePanelProps`

## Canonical Types

Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.

- `Collapsible.Root.State`: `CollapsibleRootState`
- `Collapsible.Root.Props`: `CollapsibleRootProps`
- `Collapsible.Root.ChangeEventReason`: `CollapsibleRootChangeEventReason`
- `Collapsible.Root.ChangeEventDetails`: `CollapsibleRootChangeEventDetails`
- `Collapsible.Trigger.State`: `CollapsibleTriggerState`
- `Collapsible.Trigger.Props`: `CollapsibleTriggerProps`
- `Collapsible.Panel.State`: `CollapsiblePanelState`
- `Collapsible.Panel.Props`: `CollapsiblePanelProps`