# Checkbox

## Overview

A binary toggle that lets users select or deselect a single option, or mark multiple independent options in a list. Built on Radix UI with accessible keyboard behavior and ARIA roles.

---

## When to Use

- Multi-select option lists (permissions, feature flags, filter tags)
- "Agree to terms" consent fields
- Row selection in tables
- Individual boolean settings

## When NOT to Use

- Mutually exclusive choices (only one can be true) — use `<RadioGroup>` instead.
- A single prominent on/off toggle — use `<Switch>` instead.

---

## Props

| Prop              | Type                         | Default | Required | Description                                       |
| ----------------- | ---------------------------- | ------- | -------- | ------------------------------------------------- |
| `id`              | `string`                     | —       | No       | Associates with `<Label htmlFor="...">`           |
| `size`            | `'sm' \| 'md' \| 'lg'`       | `'md'`  | No       | Size variant controlling the checkbox dimensions. |
| `checked`         | `boolean`                    | —       | No       | Controlled checked state                          |
| `defaultChecked`  | `boolean`                    | `false` | No       | Uncontrolled initial state                        |
| `onCheckedChange` | `(checked: boolean) => void` | —       | No       | Change handler                                    |
| `disabled`        | `boolean`                    | `false` | No       | Disables interaction                              |
| `className`       | `string`                     | —       | No       | Additional CSS classes                            |

---

## Examples

### Standalone with Label

```tsx
import { Checkbox, Label } from 'xertica-ui/ui';

<div className="flex items-center space-x-2">
  <Checkbox id="terms" />
  <Label htmlFor="terms">
    I agree to the{' '}
    <a href="/terms" className="underline">
      terms of service
    </a>
  </Label>
</div>;
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="acceptTerms"
  render={({ field }) => (
    <FormItem className="flex items-center space-x-2">
      <FormControl>
        <Checkbox checked={field.value} onCheckedChange={field.onChange} />
      </FormControl>
      <FormLabel>Accept Terms</FormLabel>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## AI Rules

- **Do not spread `{...field}`** on `<Checkbox>` — use `checked={field.value}` and `onCheckedChange={field.onChange}` explicitly.
- **Sizing** — Matches the standard form sizing scale (`sm`, `md`, `lg`). Ensure the size matches the surrounding inputs and labels.
- Always pair with a `<Label>` linked via `htmlFor` for accessibility.
- For mutually exclusive choices, use `<RadioGroup>` instead.

---

## Related Components

- [`RadioGroup`](./radio-group.md) — For single-choice selections
- [`Switch`](./switch.md) — For prominent on/off toggles
- [`Form`](./form.md)