# Checkbox

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Checkbox } from "@/components/starwind/checkbox";
---

<Checkbox id="demo-checkbox" label="Checkbox" />
```
  </div>
  <div slot="react">
```tsx
import { Checkbox } from "@/components/starwind/checkbox";

export function Example() {
  return (
    <Checkbox id="demo-checkbox" label="Checkbox" />
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add checkbox
```

## Usage

### variant

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

<Checkbox id="default" label="Default" variant="default" defaultChecked />
<Checkbox id="primary" label="Primary" variant="primary" defaultChecked />
<Checkbox id="secondary" label="Secondary" variant="secondary" defaultChecked />
<Checkbox id="info" label="Info" variant="info" defaultChecked />
<Checkbox id="success" label="Success" variant="success" defaultChecked />
<Checkbox id="warning" label="Warning" variant="warning" defaultChecked />
<Checkbox id="error" label="Error" variant="error" defaultChecked />
```

> **Info:** Use `defaultChecked` for mutable uncontrolled examples. `checked` is reserved for a framework
adapter that owns and resynchronizes controlled state.

### size

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

<Checkbox id="small" label="Small" size="sm" />
<Checkbox id="medium" label="Medium" size="md" />
<Checkbox id="large" label="Large" size="lg" />
```

### disabled

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

<Checkbox id="disabled" label="Disabled" disabled />
<Checkbox id="disabled-checked" label="Disabled Checked" disabled defaultChecked />
```

> **Info:** The disabled checked example also uses `defaultChecked`, preserving an uncontrolled initial state
even though interaction is disabled.

## Framework Availability
Checkbox is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### Checkbox
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultChecked` | `boolean` | No | - | Primitive override | Sets the initial checked state when the choice is uncontrolled. |
| `label` | `string` | No | - | Wrapper prop | Provides accessible text for the component. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `variant` | `"default" \| "primary" \| "secondary" \| "info" \| "success" \| "warning" \| "error"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits span attributes. Omits `defaultChecked`, `id`, and `onChange`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Checkbox Primitive](/docs/primitives/checkbox/)
- Runtime factory: [`createCheckbox`](/docs/runtime/#create-checkbox) from `@starwind-ui/runtime/checkbox`

## Changelog

### v2.0.0

- Rebuilt Checkbox on Starwind Runtime for checked state, native form participation, and checked-change events.
- See the [Checkbox Primitive](/docs/primitives/checkbox/) for the underlying unstyled anatomy and behavior API.

### v1.4.3 

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.4.1 

- add `aria-invalid` styling

### v1.4.0 

- style and focus state updates

### v1.3.0

- Add a `data-slot` attribute to all components to enable global styling updates

### v1.2.0

- No longer require an "id" prop
- Adjust component to use type `VariantProps` from `tailwind-variants`. This provides greater type safety and cleans up component frontmatter.

### v1.1.0

- `tailwind-variants` now implemented. This uses `tailwind-merge` under the hood to merge Tailwind classes without style conflicts, allowing you to override any existing classes using the "class" prop.