# Accordion Primitive

Accordion is a Starwind Runtime primitive in the controlled-value-group 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 Accordion anatomy with the Runtime wiring included.
```astro
---
import { Accordion } from "@starwind-ui/astro/accordion";
---

<Accordion.Root>
  <Accordion.Item value="details">
    <Accordion.Header>
      <Accordion.Trigger>Toggle details</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Panel>Accordion panel content</Accordion.Panel>
  </Accordion.Item>
</Accordion.Root>
```

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

export function Example() {
  return (
    <Accordion.Root>
      <Accordion.Item value="details">
        <Accordion.Header>
          <Accordion.Trigger>Toggle details</Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Panel>Accordion panel content</Accordion.Panel>
      </Accordion.Item>
    </Accordion.Root>
  );
}
```

### HTML
Render the Accordion data-sw-* contract yourself, then initialize createAccordion.
```html
<div data-sw-accordion>
  <div data-sw-accordion-item data-value="details">
    <h3 data-sw-accordion-header>
      <button data-sw-accordion-trigger type="button">Toggle details</button>
    </h3>
    <div data-sw-accordion-content role="region" hidden>Accordion panel content</div>
  </div>
</div>

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

  const root = document.querySelector("[data-sw-accordion]");
  if (root) {
    createAccordion(root);
  }
</script>
```

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

<template>
  <Accordion.Root>
    <Accordion.Item value="details">
      <Accordion.Header>
        <Accordion.Trigger>Toggle details</Accordion.Trigger>
      </Accordion.Header>
      <Accordion.Panel>Accordion panel content</Accordion.Panel>
    </Accordion.Item>
  </Accordion.Root>
</template>
```
## API Reference
### Root
The main element that owns the Accordion Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-accordion` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `AccordionValue` | - | control | Controls the current Accordion value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `AccordionValue` | - | control | Sets the initial Accordion value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| type | `"single" \| "multiple"` | "single" | option | Sets the native type for the Root part. | - |
| collapsible | `boolean` | true | option | Allows all Accordion items to be collapsed. | - |
| onValueChange | `(value: AccordionValue, details: AccordionValueChangeDetails) => void` | - | callback | Runs when the Accordion value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-type` | prop | - | Reflects the type prop on the Root part. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-collapsible` | prop | - | Reflects the collapsible 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 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `AccordionValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Accordion value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `AccordionValue` | AccordionValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Accordion. | 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 |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Accordion value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion`, `data-type`, `data-default-value`, `data-collapsible`, `data-state` | The root needs type, default value, collapsibility, and initial closed state before controller hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Item
An interactive item inside the Accordion collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-accordion-item` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `string` | - | option | Controls the current Accordion value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Item part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
| `data-state` | state | - | Reflects the current state on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion-item`, `data-value`, `data-disabled`, `data-state` | Items need stable value, disabled, and closed-state markers before trigger and panel ids are linked. |

### Header
The header container for a Accordion item.
| Fact | Value |
| --- | --- |
| Default element | `h3` |
| Discovery hook | `data-sw-accordion-header` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-header` | runtime | - | Marks the Header part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| header | Yes |

### Trigger
The control that opens, closes, or targets the Accordion content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-accordion-trigger` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-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 |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion-trigger`, `type`, `aria-expanded`, `data-state` | Triggers need button semantics and collapsed affordances before the runtime wires aria-controls. |

### Panel
The content panel controlled by Accordion.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-accordion-content` |
| Role | `region` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-accordion-content` | runtime | - | Marks the Panel part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Panel part. |
#### Refs
| Part | Public |
| --- | --- |
| panel | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-accordion-content`, `data-state`, `hidden` | Panels start hidden and closed; the runtime controls height variables and close-animation visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createAccordion`](/docs/runtime/#create-accordion) |
| Import | `@starwind-ui/runtime/accordion` |
| Root part | root |
| Option props | type, defaultValue, collapsible, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Accordion](/docs/components/accordion/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/accordion` | `createAccordion` |
| Astro Primitive | `@starwind-ui/astro/accordion` | `Accordion`, `AccordionRoot`, `AccordionItem`, `AccordionHeader`, `AccordionTrigger`, `AccordionPanel` |
| React Primitive | `@starwind-ui/react/accordion` | `Accordion`, `AccordionRoot`, `AccordionItem`, `AccordionHeader`, `AccordionTrigger`, `AccordionPanel` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Accordion` |
| runtime-factory | `createAccordion` |
| part | `Accordion.Root` |
| part | `Accordion.Item` |
| part | `Accordion.Header` |
| part | `Accordion.Trigger` |
| part | `Accordion.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.3
- 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.2
- Made value-change proposals synchronously cancelable before uncontrolled state commits.
### v0.1.1
- Made single-value accordions collapsible by default while preserving the option to require one item to remain open.
### v0.1.0
- Introduced Runtime-managed single and multiple disclosure state, keyboard navigation, and panel presence.