# 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
### 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| checked | `boolean` | - | control | Controls the checked state when a framework adapter owns it. |
| defaultChecked | `boolean` | false | control | Sets the initial uncontrolled checked state. |
| 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. |
| 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. |
#### 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 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 | - | `data-indeterminate` | - | `setIndeterminate` | Tracks whether Checkbox is in a mixed state. | 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. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | CheckboxCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Checkbox. |
#### 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 |
| --- | --- | --- | --- | --- |
| 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` |