Checkbox Group Primitive
Checkbox Group 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 CheckboxGroup anatomy with the Runtime wiring included.
---import { CheckboxGroup } from "@starwind-ui/astro/checkbox-group";---
<CheckboxGroup.Root />Use the React primitive adapter when CheckboxGroup state participates in React rendering.
import { CheckboxGroup } from "@starwind-ui/react/checkbox-group";
export function Example() { return ( <CheckboxGroup.Root /> );}Render the CheckboxGroup data-sw-* contract yourself, then initialize createCheckboxGroup.
<div data-sw-checkbox-group role="group"></div>
<script type="module"> import { createCheckboxGroup } from "@starwind-ui/runtime/checkbox-group";
const root = document.querySelector("[data-sw-checkbox-group]"); if (root) { createCheckboxGroup(root); }</script>API Reference
Root
The main element that owns the Checkbox Group Runtime instance.
- Default element
- div
- Discovery hook
- data-sw-checkbox-group
- Role
- group
Props
value CheckboxGroupValue -
- Description
- Controls the current Checkbox Group value.
- Kind
- control
- Targets
- -
- Full type
- CheckboxGroupValue
- React
Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.
valuedefaultValueonValueChange
- Astro
Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.
valuedefaultValuestarwind:value-changesetValue
- Runtime / HTML
Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.
data-default-valuestarwind:value-changesetValue
defaultValue CheckboxGroupValue -
- Description
- Sets the initial Checkbox Group value for uncontrolled usage.
- Kind
- control
- Targets
- -
- Full type
- CheckboxGroupValue
- React
Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.
valuedefaultValueonValueChange
- Astro
Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.
valuedefaultValuestarwind:value-changesetValue
- Runtime / HTML
Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.
data-default-valuestarwind:value-changesetValue
disabled boolean false
- Description
- Disables the Root part.
- Kind
- option
- Targets
- -
- Full type
- boolean
onValueChange (value: CheckboxGroupValue, details: CheckboxGroupValueChangeDetails) => void -
- Description
- Runs when the Checkbox Group value changes.
- Kind
- callback
- Targets
- -
- Full type
- (value: CheckboxGroupValue, details: CheckboxGroupValueChangeDetails) => void
- React
Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.
valuedefaultValueonValueChange
- Astro
Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.
valuedefaultValuestarwind:value-changesetValue
- Runtime / HTML
Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.
data-default-valuestarwind:value-changesetValue
Events
valueChange onValueChange value: CheckboxGroupValue
- Description
- Fires when the value changes for Checkbox Group.
- DOM event
- starwind:value-change
- Details type
- CheckboxGroupValueChangeDetails
- 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
value CheckboxGroupValue value / defaultValue
- Description
- Tracks the current Checkbox Group 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.
valuedefaultValueonValueChange
- Astro
Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.
valuedefaultValuestarwind:value-changesetValue
- Runtime / HTML
Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.
data-default-valuestarwind:value-changesetValue
Data Attributes
Runtime hooks
State
Metadata
Runtime API
- Factory
createCheckboxGroup- Import
@starwind-ui/runtime/checkbox-group- Root hook
- root
data-sw-checkbox-group - Option props
- defaultValue, disabled, value
Runtime Setters
Related Styled Components
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 grouped checkbox value ownership, shared disabled state, and form participation.