# Checkbox

> Custom-box checkbox with checked/indeterminate/invalid/disabled states.

- Group: Forms
- Status: stable
- HTML page: https://design.ipmnx.com/components/checkbox/
- Spec: https://design.ipmnx.com/design/#nx-checkbox

## Preview

**Checked / unchecked**

```html
<label class="nx-checkbox">
  <input type="checkbox" checked>
  <span class="nx-checkbox__box"></span>
  Email notifications
</label>
<label class="nx-checkbox">
  <input type="checkbox">
  <span class="nx-checkbox__box"></span>
  SMS notifications
</label>
```

```tsx
<NxCheckbox label="Email notifications" defaultChecked />
<NxCheckbox label="SMS notifications" />
```

## Variants

### Indeterminate

No HTML attribute for indeterminate: it's set as a DOM property after mount.

```html
<label class="nx-checkbox">
  <input type="checkbox" id="cb-indet-demo">
  <span class="nx-checkbox__box"></span>
  Select all (partial)
</label>
```

```tsx
<input
  type="checkbox"
  ref={(el) => { if (el) el.indeterminate = true; }}
/>
```

## API

### React props (NxKit)

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `ReactNode` | `undefined` |   | Rendered after the box, inside the `<label>`. |

### Classes

| Class | Description |
| --- | --- |
| `.nx-checkbox` | Label wrapper, 24px+ tap target |
| `.nx-checkbox__box` | 18×18 custom box |

## States

### indeterminate

```html
<label class="nx-checkbox"><input type="checkbox" id="cb-indet"><span class="nx-checkbox__box"></span>Indeterminate</label>
```

### invalid

```html
<label class="nx-checkbox"><input type="checkbox" aria-invalid="true" aria-describedby="err-agb"><span class="nx-checkbox__box"></span>Accept the terms</label><span class="nx-field__error" id="err-agb"><span aria-hidden="true">✕</span> Consent required</span>
```

### disabled

```html
<label class="nx-checkbox"><input type="checkbox" checked disabled><span class="nx-checkbox__box"></span>Locked</label>
```

## Accessibility

- Indeterminate is a DOM property, not an HTML attribute. Set el.indeterminate = true after mount (React: a ref callback).
- Icon-only usage (no visible label text) still needs an accessible name via aria-label on the input; the width-axis tap-target floor applies via :has(input:not([id])).

## Do / Don't

- Do: Wrap the input + box + label text in one `<label>`.
- Don't try to set indeterminate via a static HTML attribute. It silently does nothing.

## Related

- [Radio](https://design.ipmnx.com/components/radio.md)
- [Switch](https://design.ipmnx.com/components/switch.md)

---

Source: registry.js (NX Design System)
