# Collapsible Primitive

Collapsible is a Starwind Runtime primitive in the presence-disclosure-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## 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>
```

### Vue
Use the Vue 3.5 beta adapter to render Collapsible anatomy.
```vue
<script setup lang="ts">
import Collapsible from "@starwind-ui/vue/collapsible";
</script>

<template>
  <Collapsible.Root>
    <Collapsible.Trigger>Toggle details</Collapsible.Trigger>
    <Collapsible.Panel>Collapsible content</Collapsible.Panel>
  </Collapsible.Root>
</template>
```
## 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 | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Collapsible is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Collapsible starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| onOpenChange | `(open: boolean, details: CollapsibleOpenChangeDetails) => void` | - | callback | Runs when Collapsible opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### 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:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | CollapsibleOpenChangeDetails | before-state-commit | Yes | Fires when Collapsible opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### 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 | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| 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 | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| 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` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced controlled and uncontrolled open state with trigger and panel presence.