On this page

Checkbox Primitive

Checkbox coordinates a visible boolean control, indicator presence, and hidden form inputs for boolean form state.

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

defaultChecked boolean false

Description: Sets the initial uncontrolled checked state.
Kind: control
Targets: -
Full type: boolean

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

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

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

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
State control support: React supports controlled and default state with checked and defaultChecked props. Runtime/HTML reads initial state from data-default-checked, emits starwind:checked-change, and updates with setChecked. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.

indeterminate boolean indeterminate

Description: Tracks whether Checkbox is in a mixed state.
Initial attribute: data-indeterminate
Runtime getter: -
Runtime setter: setIndeterminate
State control support: React supports controlled state with the indeterminate prop. Runtime/HTML reads initial state from data-indeterminate and updates with setIndeterminate. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.

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

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