# 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
### Astro
Use the Astro primitive adapter to render Checkbox anatomy with the Runtime wiring included.
```astro
---
import { Checkbox } from "@starwind-ui/astro/checkbox";
---

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

### React
Use the React primitive adapter when Checkbox state participates in React rendering.
```tsx
import { Checkbox } from "@starwind-ui/react/checkbox";

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

### HTML
Render the Checkbox data-sw-* contract yourself, then initialize createCheckbox.
```html
<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>
```

### Vue
Use the Vue 3.5 beta adapter to render Checkbox anatomy.
```vue
<script setup lang="ts">
import Checkbox from "@starwind-ui/vue/checkbox";
</script>

<template>
  <Checkbox.Root>
    <Checkbox.Indicator />
  </Checkbox.Root>
</template>
```
## API Reference
### Root
The focusable checkbox control. It owns the Runtime instance and carries ARIA, checked, indeterminate, disabled, and form option state.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-checkbox` |
| Role | `checkbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| checked | `boolean` | - | control | Controls the checked state when a framework adapter owns it. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| defaultChecked | `boolean` | false | control | Sets the initial uncontrolled checked state. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| disabled | `boolean` | false | option | Prevents interaction and marks the control disabled. | - |
| form | `string` | - | option | Associates the hidden native input with an external form. | - |
| id | `string` | - | option | Sets the hidden native input id. | - |
| indeterminate | `boolean` | false | control | Sets the mixed visual state independently from checked state. | **React:** Use indeterminate for controlled state.<br>**Astro:** Use indeterminate for initial state and call setIndeterminate for later updates.<br>**Runtime / HTML:** Use data-indeterminate for initial state and call setIndeterminate for later updates. |
| name | `string` | - | option | Sets the submitted form field name. | - |
| nativeButton | `boolean` | false | rendering | Renders the root as a native button instead of a span. | - |
| readOnly | `boolean` | false | option | Marks the checkbox readonly for assistive technology. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| uncheckedValue | `string` | - | option | Value submitted by the runtime-created unchecked input. | - |
| value | `string` | - | option | Value submitted by the checked input. | - |
| onCheckedChange | `(checked: boolean, details: CheckboxCheckedChangeDetails) => void` | - | callback | Receives checked-change details before state commits. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox` | 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` | prop | - | Present when the checkbox is disabled. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-id` | prop | - | Reflects the id prop on the Root part. |
| `data-indeterminate` | state | - | Present when the checkbox is in the mixed state. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-unchecked` | state | - | Present when the checkbox is unchecked. |
| `data-unchecked-value` | prop | - | Reflects the unchecked value prop on the Root part. |
| `data-value` | prop | - | Reflects the value prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | `getChecked` | `setChecked` | Tracks whether Checkbox is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| indeterminate | `boolean` | indeterminate | - | `data-indeterminate` | - | `setIndeterminate` | Tracks whether Checkbox is in a mixed state. | **React:** Use indeterminate for controlled state.<br>**Astro:** Use indeterminate for initial state and call setIndeterminate for later updates.<br>**Runtime / HTML:** Use data-indeterminate for initial state and call setIndeterminate for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | CheckboxCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Checkbox. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setChecked` | state: checked | emit: false | Yes | Updates whether Checkbox is checked from Runtime code. |
| `setIndeterminate` | state: indeterminate | emit: false | Yes | Updates whether Checkbox is in a mixed state from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Checkbox is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| checkbox-group | consumes | disabled, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-checkbox`, `role`, `aria-checked`, `data-checked`, `data-unchecked`, `data-default-checked`, `data-disabled`, `data-indeterminate` | The visible ARIA control needs correct semantics before controller hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Indicator
The visual indicator rendered inside the root for checked or mixed state.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-checkbox-indicator` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| keepMounted | `boolean` | false | rendering | Keeps the indicator element mounted when unchecked. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox-indicator` | runtime | - | Runtime discovery hook for the indicator part. |
| `data-keep-mounted` | prop | - | Marks that the indicator should stay mounted when unchecked. |
| `data-unchecked` | state | - | Present while the checkbox is unchecked. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | keepMounted |

### Input
The hidden native checkbox input synchronized by the Runtime for form submission.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-checkbox-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox-input` | runtime | - | Runtime discovery hook for the hidden checked input. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-checkbox-input` | The runtime needs the nested input placeholder so it can attach form state after hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Unchecked Input
The hidden unchecked input created or synchronized by the Runtime when unchecked values are needed.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-checkbox-unchecked-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-checkbox-unchecked-input` | runtime | - | Runtime discovery hook for the hidden unchecked input. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCheckbox`](/docs/runtime/#create-checkbox) |
| Import | `@starwind-ui/runtime/checkbox` |
| Root part | root |
| Option props | checked, defaultChecked, disabled, form, id, indeterminate, name, readOnly, required, uncheckedValue, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Checkbox](/docs/components/checkbox/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/checkbox` | `createCheckbox` |
| Astro Primitive | `@starwind-ui/astro/checkbox` | `Checkbox`, `CheckboxRoot`, `CheckboxIndicator` |
| React Primitive | `@starwind-ui/react/checkbox` | `Checkbox`, `CheckboxRoot`, `CheckboxIndicator` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Checkbox` |
| runtime-factory | `createCheckbox` |
| part | `Checkbox.Root` |
| part | `Checkbox.Indicator` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### 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.