# Checkbox

Turns a single option on or off, or picks any number of options from a list.

```tsx
import { Checkbox } from "@zenoxai/ui/components/checkbox"
import { Field, FieldLabel } from "@zenoxai/ui/components/field"

function CheckboxDemo() {
  return (
    <Field orientation="horizontal" className="w-fit">
      <Checkbox id="notify-critical" defaultChecked />
      <FieldLabel htmlFor="notify-critical">
        Email me when a critical alert opens
      </FieldLabel>
    </Field>
  )
}
```

## Usage

```tsx
import { Checkbox } from "@zenoxai/ui/components/checkbox"
import { Field, FieldLabel } from "@zenoxai/ui/components/field"

<Field orientation="horizontal">
  <Checkbox id="notify-critical" defaultChecked />
  <FieldLabel htmlFor="notify-critical">Email me when a critical alert opens</FieldLabel>
</Field>
```

Use a checkbox for an option that takes effect when the form is saved, and for picking several
options from a short list. For a setting that applies the moment it is flipped, use a
[Switch](/components/switch). For exactly one option out of a few, use a
[Radio Group](/components/radio-group).

Pair every checkbox with a visible label. A horizontal [Field](/components/field) lays out the
box and the label and dims both when the field is disabled.

`Checkbox` is uncontrolled with `defaultChecked`, or controlled with `checked` and
`onCheckedChange(checked)`. Set `name` and `value` to submit it with a native form.

## Examples

### With a description

Put the label and a `FieldDescription` in a `FieldContent` when the option needs a sentence of
explanation. The box aligns with the first line of the label.

```tsx
import { Checkbox } from "@zenoxai/ui/components/checkbox"
import { Field, FieldContent, FieldDescription, FieldLabel } from "@zenoxai/ui/components/field"

function CheckboxWithDescription() {
  return (
    <Field orientation="horizontal" className="max-w-sm">
      <Checkbox id="auto-close" />
      <FieldContent>
        <FieldLabel htmlFor="auto-close">Close resolved alerts</FieldLabel>
        <FieldDescription>
          Alerts with no new events for 7 days move to Closed.
        </FieldDescription>
      </FieldContent>
    </Field>
  )
}
```

### Disabled

Set `disabled` on the checkbox and `data-disabled` on the `Field`, so the label dims with it.

```tsx
import { Checkbox } from "@zenoxai/ui/components/checkbox"
import { Field, FieldGroup, FieldLabel } from "@zenoxai/ui/components/field"

function CheckboxDisabled() {
  return (
    <FieldGroup className="w-56 gap-3">
      <Field orientation="horizontal" data-disabled>
        <Checkbox id="sso-enforced" defaultChecked disabled />
        <FieldLabel htmlFor="sso-enforced">Require single sign-on</FieldLabel>
      </Field>
      <Field orientation="horizontal" data-disabled>
        <Checkbox id="api-access" disabled />
        <FieldLabel htmlFor="api-access">Allow API access</FieldLabel>
      </Field>
    </FieldGroup>
  )
}
```

### Invalid

Set `aria-invalid` on the checkbox and `data-invalid` on the `Field`, and say what to do in a
`FieldError`.

```tsx
import { Checkbox } from "@zenoxai/ui/components/checkbox"
import { Field, FieldContent, FieldError, FieldLabel } from "@zenoxai/ui/components/field"

function CheckboxInvalid() {
  return (
    <Field orientation="horizontal" data-invalid className="max-w-sm">
      <Checkbox id="purge-ack" required aria-invalid />
      <FieldContent>
        <FieldLabel htmlFor="purge-ack">
          I understand that purged events cannot be restored
        </FieldLabel>
        <FieldError>Confirm this to purge the events.</FieldError>
      </FieldContent>
    </Field>
  )
}
```

### Controlled list

Group related checkboxes in a `FieldSet` with a `FieldLegend`, and keep the selection in state
when other parts of the view depend on it.

```tsx
import * as React from "react"
import { Checkbox } from "@zenoxai/ui/components/checkbox"
import { Field, FieldDescription, FieldGroup, FieldLabel, FieldLegend, FieldSet } from "@zenoxai/ui/components/field"

function CheckboxControlled() {
  const severities = ["Critical", "High", "Medium", "Low"]
  const [selected, setSelected] = React.useState(["Critical", "High"])

  return (
    <FieldSet className="w-fit">
      <FieldLegend variant="label">Notify on severity</FieldLegend>
      <FieldGroup className="gap-3">
        {severities.map((severity) => (
          <Field key={severity} orientation="horizontal">
            <Checkbox
              id={`severity-${severity}`}
              checked={selected.includes(severity)}
              onCheckedChange={(checked) =>
                setSelected((current) =>
                  checked
                    ? [...current, severity]
                    : current.filter((value) => value !== severity)
                )
              }
            />
            <FieldLabel htmlFor={`severity-${severity}`}>{severity}</FieldLabel>
          </Field>
        ))}
      </FieldGroup>
      <FieldDescription>
        {selected.length === 0
          ? "No notifications."
          : `Notifying on ${selected.length} of ${severities.length} severities.`}
      </FieldDescription>
    </FieldSet>
  )
}
```

## Accessibility

- The checkbox renders a `<span role="checkbox">` with a hidden `<input>` beside it. The `id`
  goes to the hidden input, so `<FieldLabel htmlFor>` (or a wrapping label) names the checkbox
  and toggles it on click.
- Space toggles the focused checkbox. `aria-checked` and `data-checked` follow the
  state.
- `indeterminate` sets `aria-checked="mixed"` and draws a dash instead of a check mark: use it
  for a "select all" box when only some of the items are selected.
- Put a group of checkboxes in a `FieldSet` with a `FieldLegend` so screen readers announce the
  group name with each option.

## API reference

`import { ... } from "@zenoxai/ui/components/checkbox"`

### Checkbox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | `boolean` | `undefined` | Whether the checkbox is currently ticked.  To render an uncontrolled checkbox, use the `defaultChecked` prop instead. |
| defaultChecked | `boolean` | `false` | Whether the checkbox is initially ticked.  To render a controlled checkbox, use the `checked` prop instead. |
| disabled | `boolean` | `false` | Whether the component should ignore user interaction. |
| form | `string` |  | Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form. |
| id | `string` |  | The id of the input element. |
| indeterminate | `boolean` | `false` | Whether the checkbox is in a mixed state: neither ticked, nor unticked. |
| inputRef | `Ref<HTMLInputElement>` |  | A ref to access the hidden `<input>` element. |
| name | `string` | `undefined` | Identifies the field when a form is submitted. |
| nativeButton | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| onCheckedChange | `((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void)` |  | Event handler called when the checkbox is ticked or unticked. |
| parent | `boolean` | `false` | Whether the checkbox controls a group of child checkboxes.  Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group). |
| readOnly | `boolean` | `false` | Whether the user should be unable to tick or untick the checkbox. |
| render | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, CheckboxRootState>` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |
| required | `boolean` | `false` | Whether the user must tick the checkbox before submitting a form. |
| uncheckedValue | `string` |  | The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior. |
| value | `string` |  | The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on". |