On this page

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

Use the Astro primitive adapter to render Accordion anatomy with the Runtime wiring included.

---
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>

Use the React primitive adapter when Accordion state participates in React rendering.

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>
  );
}

Render the Accordion data-sw-* contract yourself, then initialize createAccordion.

<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>

API Reference

Root

The main element that owns the Accordion Runtime instance.

Default element: div
Discovery hook: data-sw-accordion
Role: -

Props

Prop Type Default

value AccordionValue -

Description

Controls the current Accordion value.

Kind

control

Targets

root

Full type

AccordionValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

defaultValue AccordionValue -

Description

Sets the initial Accordion value for uncontrolled usage.

Kind

control

Targets

Full type

AccordionValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

type "single" | "multiple" "single"

Description: Sets the native type for the Root part.
Kind: option
Targets: -
Full type: "single" | "multiple"

collapsible boolean true

Description: Allows all Accordion items to be collapsed.
Kind: option
Targets: -
Full type: boolean

onValueChange (value: AccordionValue, details: AccordionValueChangeDetails) => void -

Description

Runs when the Accordion value changes.

Kind

callback

Targets

Full type

(value: AccordionValue, details: AccordionValueChangeDetails) => void

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Events

Event Callback Value

valueChange onValueChange value: AccordionValue

Description

Fires when the value changes for Accordion.

DOM event

starwind:value-change

Details type

AccordionValueChangeDetails

Timing

before-state-commit

Cancelable

Yes

Cancellation sequence

Check internal eligibility and intent.
Create one details object for the proposal.
Call the Runtime callback with the details object when the controller exposes one.
Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
Read details.isCanceled, including cancellation caused by preventDefault().
Apply the accepted state.
Notify Runtime subscribers and other accepted-only observers.

State

State Type Props

value AccordionValue value / defaultValue

Description

Tracks the current Accordion value.

Initial attribute

data-default-value

Runtime getter

getValue

Runtime setter

setValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-accordion - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Root part.

Metadata

Attribute Value Description

data-type - Reflects the type prop on the Root part.

data-default-value - Reflects the default value prop on the Root part.

data-collapsible - Reflects the collapsible prop on the Root part.

Item

An interactive item inside the Accordion collection.

Default element: div
Discovery hook: data-sw-accordion-item
Role: -

Props

Prop Type Default

value string -

Description

Controls the current Accordion value.

Kind

option

Targets

item

Full type

string

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

disabled boolean false

Description: Disables the Item part.
Kind: option
Targets: item
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-accordion-item - Marks the Item part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Item part.

Metadata

Attribute Value Description

data-value - Reflects the value prop on the Item part.

data-disabled - Reflects the disabled prop on the Item part.

The header container for a Accordion item.

Default element: h3
Discovery hook: data-sw-accordion-header
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-accordion-header - Marks the Header part so Starwind Runtime can find it.

Trigger

The control that opens, closes, or targets the Accordion content.

Default element: button
Discovery hook: data-sw-accordion-trigger
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-accordion-trigger - Marks the Trigger part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Trigger part.

Panel

The content panel controlled by Accordion.

Default element: div
Discovery hook: data-sw-accordion-content
Role: region

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-accordion-content - Marks the Panel part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Panel part.

Runtime API

Factory: createAccordion
Import: @starwind-ui/runtime/accordion
Root hook: root data-sw-accordion
Option props: type, defaultValue, collapsible, value

Runtime Setters

Method Target Description

setValue state: value Updates the current Accordion value from Runtime code.

Component Relationship

Accordion Direct primitive

Changelog

View version history v1.0.0 5 releases

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.

Layer Metadata

Accordion Primitive uses createAccordion. Styled components: Accordion.

primitive Accordion Primitive Accordion Primitive uses createAccordion. Styled components: Accordion. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters accordion Accordion Controlled Value Group Grouped controls coordinated by a shared selected value. /docs/primitives/accordion/ createAccordion @starwind-ui/runtime/accordion /docs/runtime/#create-accordion root type defaultValue collapsible value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Accordion data-sw-* contract yourself, then initialize createAccordion. html Use the Astro primitive adapter to render Accordion anatomy with the Runtime wiring included. Use the React primitive adapter when Accordion state participates in React rendering. tsx div data-sw-accordion AccordionValue Controls the current Accordion value. Sets the initial Accordion value for uncontrolled usage. "single" | "multiple" Sets the native type for the Root part. boolean Allows all Accordion items to be collapsed. onValueChange (value: AccordionValue, details: AccordionValueChangeDetails) => void AccordionValueChangeDetails Runs when the Accordion value changes. 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 Reflects the default value prop on the Root part. data-collapsible Reflects the collapsible prop on the Root part. data-state state Reflects the current state on the Root part. getValue setValue valueChange starwind:value-change item data-sw-accordion-item string disabled Disables the Item part. Marks the Item part so Starwind Runtime can find it. data-value Reflects the value prop on the Item part. data-disabled Reflects the disabled prop on the Item part. Reflects the current state on the Item part. header h3 data-sw-accordion-header Marks the Header part so Starwind Runtime can find it. trigger button data-sw-accordion-trigger Marks the Trigger part so Starwind Runtime can find it. Reflects the current state on the Trigger part. panel data-sw-accordion-content region Marks the Panel part so Starwind Runtime can find it. Reflects the current state on the Panel part. Root Item Header Trigger aria-expanded Panel hidden @starwind-ui/astro @starwind-ui/astro/accordion Render closed/default-open placeholders and self-initialize; runtime owns item discovery, ids, keyboard navigation, and panel animation. @starwind-ui/react @starwind-ui/react/accordion Bridge controlled value through setValue without emitting duplicate events; type, defaultValue, and collapsible recreate the controller. /docs/components/accordion/ Direct primitive direct-primitive Styled component Accordion

Accordion Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Item

Props

Data Attributes

Runtime hooks

State

Metadata

Header

Data Attributes

Runtime hooks

Trigger

Data Attributes

Runtime hooks

State

Panel

Data Attributes

Runtime hooks

State

Runtime API

Runtime Setters

Related Styled Components

Changelog

v1.0.0

v0.1.3

v0.1.2

v0.1.1

v0.1.0