# Collapsible Primitive

Collapsible is a Starwind Runtime primitive in the presence-disclosure-control contract family.
## Anatomy
### Astro
Use the Astro primitive adapter to render Collapsible anatomy with the Runtime wiring included.
```astro
---
import { Collapsible } from "@starwind-ui/astro/collapsible";
---

<Collapsible.Root>
  <Collapsible.Trigger>Toggle details</Collapsible.Trigger>
  <Collapsible.Panel>Collapsible content</Collapsible.Panel>
</Collapsible.Root>
```

### React
Use the React primitive adapter when Collapsible state participates in React rendering.
```tsx
import { Collapsible } from "@starwind-ui/react/collapsible";

export function Example() {
  return (
    <Collapsible.Root>
      <Collapsible.Trigger>Toggle details</Collapsible.Trigger>
      <Collapsible.Panel>Collapsible content</Collapsible.Panel>
    </Collapsible.Root>
  );
}
```

### HTML
Render the Collapsible data-sw-* contract yourself, then initialize createCollapsible.
```html
<div data-sw-collapsible>
  <button data-sw-collapsible-trigger>Toggle details</button>
  <div data-sw-collapsible-panel hidden>Collapsible content</div>
</div>

<script type="module">
  import { createCollapsible } from "@starwind-ui/runtime/collapsible";

  const root = document.querySelector("[data-sw-collapsible]");
  if (root) {
    createCollapsible(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Collapsible Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-collapsible` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Collapsible is open. |
| defaultOpen | `boolean` | false | control | Sets whether Collapsible starts open. |
| disabled | `boolean` | false | option | Disables the Root part. |
| onOpenChange | `(open: boolean, details: CollapsibleOpenChangeDetails) => void` | - | callback | Runs when Collapsible opens or closes. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-collapsible` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Collapsible is open. | React supports controlled and default state with open and defaultOpen props. Runtime/HTML reads initial state from data-default-open, emits starwind:open-change, and updates with setOpen. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | CollapsibleOpenChangeDetails | before-state-commit | Yes | Fires when Collapsible opens or closes. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Collapsible from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-collapsible`, `data-default-open`, `data-disabled`, `data-state` | The disclosure root needs initial open/closed state for styling before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Collapsible content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-collapsible-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| asChild | `boolean` | false | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-collapsible-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-collapsible-trigger`, `aria-expanded`, `data-state` | The trigger starts with stable disclosure affordances; the runtime wires ids and aria-controls after initialization. |

### Panel
The content panel controlled by Collapsible.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-collapsible-panel` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| hiddenUntilFound | `boolean` | false | rendering | Changes how the Panel part is rendered. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-collapsible-panel` | runtime | - | Marks the Panel part so Starwind Runtime can find it. |
| `data-hidden-until-found` | prop | - | Reflects the hidden until found prop on the Panel part. |
| `data-state` | state | - | Reflects the current state on the Panel part. |
#### Refs
| Part | Public |
| --- | --- |
| panel | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-collapsible-panel`, `data-hidden-until-found`, `data-state`, `hidden` | The panel starts hidden and is revealed or animated by the runtime controller; hidden-until-found keeps opted-in closed panels discoverable by browser find-in-page. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCollapsible`](/docs/runtime/#create-collapsible) |
| Import | `@starwind-ui/runtime/collapsible` |
| Root part | root |
| Option props | defaultOpen, disabled, open |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Collapsible](/docs/components/collapsible/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/collapsible` | `createCollapsible` |
| Astro Primitive | `@starwind-ui/astro/collapsible` | `Collapsible`, `CollapsibleRoot`, `CollapsibleTrigger`, `CollapsiblePanel` |
| React Primitive | `@starwind-ui/react/collapsible` | `Collapsible`, `CollapsibleRoot`, `CollapsibleTrigger`, `CollapsiblePanel` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Collapsible` |
| runtime-factory | `createCollapsible` |
| part | `Collapsible.Root` |
| part | `Collapsible.Trigger` |
| part | `Collapsible.Panel` |