On this page

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

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

---
import { Collapsible } from "@starwind-ui/astro/collapsible";
---

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

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

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

Render the Collapsible data-sw-* contract yourself, then initialize createCollapsible.

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

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

Props

Prop Type Default

open boolean -

Description

Controls whether Collapsible is open.

Kind

control

Targets

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

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

data-default-open
starwind:open-change
setOpen

defaultOpen boolean false

Description

Sets whether Collapsible starts open.

Kind

control

Targets

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

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

data-default-open
starwind:open-change
setOpen

disabled boolean false

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

onOpenChange (open: boolean, details: CollapsibleOpenChangeDetails) => void -

Description

Runs when Collapsible opens or closes.

Kind

callback

Targets

Full type

(open: boolean, details: CollapsibleOpenChangeDetails) => void

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

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

data-default-open
starwind:open-change
setOpen

Events

Event Callback Value

openChange onOpenChange open: boolean

Description

Fires when Collapsible opens or closes.

DOM event

starwind:open-change

Details type

CollapsibleOpenChangeDetails

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

open boolean open / defaultOpen

Description

Tracks whether Collapsible is open.

Initial attribute

data-default-open

Runtime getter

getOpen

Runtime setter

setOpen

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

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

data-default-open
starwind:open-change
setOpen

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-collapsible - 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-default-open - Reflects the default open prop on the Root part.

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

Trigger

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

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

Props

Prop Type Default

asChild boolean false

Description: Merges behavior onto your child element instead of rendering the default Trigger element.
Kind: rendering
Targets: trigger
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-collapsible-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 Collapsible.

Default element: div
Discovery hook: data-sw-collapsible-panel
Role: -

Props

Prop Type Default

hiddenUntilFound boolean false

Description: Changes how the Panel part is rendered.
Kind: rendering
Targets: panel
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-collapsible-panel - Marks the Panel part so Starwind Runtime can find it.

State

Attribute Value Description

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

Metadata

Attribute Value Description

data-hidden-until-found - Reflects the hidden until found prop on the Panel part.

Runtime API

Factory: createCollapsible
Import: @starwind-ui/runtime/collapsible
Root hook: root data-sw-collapsible
Option props: defaultOpen, disabled, open

Runtime Setters

Method Target Description

setOpen state: open Opens or closes Collapsible from Runtime code.

Component Relationship

Collapsible Direct primitive

Changelog

View version history v1.0.0 3 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.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.

Collapsible Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Trigger

Props

Data Attributes

Runtime hooks

State

Panel

Props

Data Attributes

Runtime hooks

State

Metadata

Runtime API

Runtime Setters

Related Styled Components

Changelog

v1.0.0

v0.1.1

v0.1.0