On this page

Checkbox Primitive

Checkbox coordinates a visible boolean control, indicator presence, and hidden form inputs for boolean form state. 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.

Usage Guidelines

Use Checkbox for one independent boolean value. Use Checkbox when users can turn a single option on or off without choosing from a required set.
Use the hidden input parts for form submission. The runtime synchronizes the hidden native input and unchecked input so unchecked and checked states can submit predictable values.

Anatomy

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

---
import { Checkbox } from "@starwind-ui/astro/checkbox";
---

<Checkbox.Root>
  <Checkbox.Indicator />
</Checkbox.Root>

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

import { Checkbox } from "@starwind-ui/react/checkbox";

export function Example() {
  return (
    <Checkbox.Root>
      <Checkbox.Indicator />
    </Checkbox.Root>
  );
}

Render the Checkbox data-sw-* contract yourself, then initialize createCheckbox.

<span data-sw-checkbox role="checkbox">
  <span data-sw-checkbox-indicator></span>
  <input data-sw-checkbox-input type="checkbox" aria-hidden="true" tabindex="-1" />
</span>

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

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

API Reference

Root

The focusable checkbox control. It owns the Runtime instance and carries ARIA, checked, indeterminate, disabled, and form option state.

Default element: span
Discovery hook: data-sw-checkbox
Role: checkbox

Props

Prop Type Default

checked boolean -

Description

Controls the checked state when a framework adapter owns it.

Kind

control

Targets

Full type

boolean

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

defaultChecked boolean false

Description

Sets the initial uncontrolled checked state.

Kind

control

Targets

Full type

boolean

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

disabled boolean false

Description: Prevents interaction and marks the control disabled.
Kind: option
Targets: -
Full type: boolean

form string -

Description: Associates the hidden native input with an external form.
Kind: option
Targets: -
Full type: string

id string -

Description: Sets the hidden native input id.
Kind: option
Targets: -
Full type: string

indeterminate boolean false

Description

Sets the mixed visual state independently from checked state.

Kind

control

Targets

Full type

boolean

React

Use indeterminate for controlled state.

indeterminate

Astro

Use indeterminate for initial state and call setIndeterminate for later updates.

indeterminate
setIndeterminate

Runtime / HTML

Use data-indeterminate for initial state and call setIndeterminate for later updates.

data-indeterminate
setIndeterminate

name string -

Description: Sets the submitted form field name.
Kind: option
Targets: -
Full type: string

nativeButton boolean false

Description: Renders the root as a native button instead of a span.
Kind: rendering
Targets: root
Full type: boolean

readOnly boolean false

Description: Marks the checkbox readonly for assistive technology.
Kind: option
Targets: -
Full type: boolean

required boolean false

Description: Marks the form control as required.
Kind: option
Targets: -
Full type: boolean

uncheckedValue string -

Description: Value submitted by the runtime-created unchecked input.
Kind: option
Targets: -
Full type: string

value string -

Description: Value submitted by the checked input.
Kind: option
Targets: -
Full type: string

onCheckedChange (checked: boolean, details: CheckboxCheckedChangeDetails) => void -

Description

Receives checked-change details before state commits.

Kind

callback

Targets

Full type

(checked: boolean, details: CheckboxCheckedChangeDetails) => void

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

Events

Event Callback Value

checkedChange onCheckedChange checked: boolean

Description

Fires when the checked state changes for Checkbox.

DOM event

starwind:checked-change

Details type

CheckboxCheckedChangeDetails

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

checked boolean checked / defaultChecked

Description

Tracks whether Checkbox is checked.

Initial attribute

data-default-checked

Runtime getter

getChecked

Runtime setter

setChecked

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

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

data-default-checked
starwind:checked-change
setChecked

indeterminate boolean indeterminate

Description

Tracks whether Checkbox is in a mixed state.

Initial attribute

data-indeterminate

Runtime getter

Runtime setter

setIndeterminate

React

Use indeterminate for controlled state.

indeterminate

Astro

Use indeterminate for initial state and call setIndeterminate for later updates.

indeterminate
setIndeterminate

Runtime / HTML

Use data-indeterminate for initial state and call setIndeterminate for later updates.

data-indeterminate
setIndeterminate

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-checkbox - Runtime discovery hook for the checkbox root.

State

Attribute Value Description

data-checked - Present when the checkbox is checked.

data-indeterminate - Present when the checkbox is in the mixed state.

data-unchecked - Present when the checkbox is unchecked.

Metadata

Attribute Value Description

data-default-checked - Initial uncontrolled checked state.

data-disabled - Present when the checkbox is disabled.

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

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

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

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

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

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

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

Indicator

The visual indicator rendered inside the root for checked or mixed state.

Default element: span
Discovery hook: data-sw-checkbox-indicator
Role: -

Props

Prop Type Default

keepMounted boolean false

Description: Keeps the indicator element mounted when unchecked.
Kind: rendering
Targets: indicator
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-checkbox-indicator - Runtime discovery hook for the indicator part.

State

Attribute Value Description

data-unchecked - Present while the checkbox is unchecked.

Metadata

Attribute Value Description

data-keep-mounted - Marks that the indicator should stay mounted when unchecked.

Input

The hidden native checkbox input synchronized by the Runtime for form submission.

Default element: input
Discovery hook: data-sw-checkbox-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-checkbox-input - Runtime discovery hook for the hidden checked input.

Unchecked Input

The hidden unchecked input created or synchronized by the Runtime when unchecked values are needed.

Default element: input
Discovery hook: data-sw-checkbox-unchecked-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-checkbox-unchecked-input - Runtime discovery hook for the hidden unchecked input.

Runtime API

Factory: createCheckbox
Import: @starwind-ui/runtime/checkbox
Root hook: root data-sw-checkbox
Option props: checked, defaultChecked, disabled, form, id, indeterminate, name, readOnly, required, uncheckedValue, value

Runtime Setters

Method Target Description

setChecked state: checked Updates whether Checkbox is checked from Runtime code.

setIndeterminate state: indeterminate Updates whether Checkbox is in a mixed state from Runtime code.

setDisabled prop: disabled Updates whether Checkbox is disabled from Runtime code.

Form Participation

Fact	Value
Form props	form, id, name, required, uncheckedValue, value
Hidden input	input (checkbox)
Field integration	Yes

Component Relationship

Checkbox Direct primitive

Changelog

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

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

Corrected React indicator presence for active, kept, and explicitly hidden indicators.

v0.1.0

Introduced checked and indeterminate state, form participation, and checked-change events.

Layer Metadata

Checkbox Primitive uses createCheckbox. Styled components: Checkbox.

primitive Checkbox Primitive Checkbox Primitive uses createCheckbox. Styled components: Checkbox. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters checkbox Checkbox Single Boolean Control Controls with a single checked, pressed, or enabled state. /docs/primitives/checkbox/ createCheckbox @starwind-ui/runtime/checkbox /docs/runtime/#create-checkbox root checked defaultChecked disabled form id indeterminate name readOnly required uncheckedValue value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Checkbox data-sw-* contract yourself, then initialize createCheckbox. html Use the Astro primitive adapter to render Checkbox anatomy with the Runtime wiring included. Use the React primitive adapter when Checkbox state participates in React rendering. tsx span data-sw-checkbox boolean Controls the checked state when a framework adapter owns it. Sets the initial uncontrolled checked state. Prevents interaction and marks the control disabled. string Associates the hidden native input with an external form. Sets the hidden native input id. Sets the mixed visual state independently from checked state. Sets the submitted form field name. nativeButton Renders the root as a native button instead of a span. Marks the checkbox readonly for assistive technology. Marks the form control as required. Value submitted by the runtime-created unchecked input. Value submitted by the checked input. onCheckedChange (checked: boolean, details: CheckboxCheckedChangeDetails) => void CheckboxCheckedChangeDetails Receives checked-change details before state commits. runtime Runtime discovery hook for the checkbox root. data-checked state Present when the checkbox is checked. data-default-checked prop Initial uncontrolled checked state. data-disabled Present when the checkbox is disabled. data-form Reflects the form prop on the Root part. data-id Reflects the id prop on the Root part. data-indeterminate Present when the checkbox is in the mixed state. data-name Reflects the name prop on the Root part. data-readonly Reflects the readonly prop on the Root part. data-required Reflects the required prop on the Root part. data-unchecked Present when the checkbox is unchecked. data-unchecked-value Reflects the unchecked value prop on the Root part. data-value Reflects the value prop on the Root part. getChecked setChecked setIndeterminate checkedChange starwind:checked-change setDisabled indicator data-sw-checkbox-indicator keepMounted Keeps the indicator element mounted when unchecked. Runtime discovery hook for the indicator part. data-keep-mounted Marks that the indicator should stay mounted when unchecked. Present while the checkbox is unchecked. input data-sw-checkbox-input Runtime discovery hook for the hidden checked input. uncheckedInput data-sw-checkbox-unchecked-input Runtime discovery hook for the hidden unchecked input. Root aria-checked aria-readonly aria-required Indicator Input type aria-hidden tabIndex Unchecked Input @starwind-ui/astro @starwind-ui/astro/checkbox Render uncontrolled initial state only; updates are runtime-owned after hydration. @starwind-ui/react @starwind-ui/react/checkbox Bridge controlled checked changes through setChecked without emitting duplicate events. /docs/components/checkbox/ Direct primitive direct-primitive Styled component Checkbox

Checkbox Primitive

Usage Guidelines

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Indicator

Props

Data Attributes

Runtime hooks

State

Metadata

Input

Data Attributes

Runtime hooks

Unchecked Input

Data Attributes

Runtime hooks

Runtime API

Runtime Setters

Form Participation

Related Styled Components

Changelog

v1.0.0

v0.1.2

v0.1.1

v0.1.0