# Checkbox

A control that toggles between checked, unchecked and indeterminate.

Source: [checkbox.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/checkbox.tsx)

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

export default function CheckboxBasic() {
  return (
    <Field orientation="horizontal" className="max-w-sm">
      <Checkbox id="accept-terms" />
      <FieldLabel htmlFor="accept-terms">Accept the terms of service</FieldLabel>
    </Field>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/checkbox
```

## Usage

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

export function TermsCheckbox() {
  return (
    <Field orientation="horizontal">
      <Checkbox />
      <FieldLabel>Accept the terms of service</FieldLabel>
    </Field>
  );
}
```

Label a checkbox with a `FieldLabel` in a horizontal [Field](https://ui.jarv.is/components/field.md). Without visible text,
give it an `aria-label`. For several checkboxes with one shared value, use
[Checkbox Group](https://ui.jarv.is/components/checkbox-group.md).

## Examples

### With a description

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

export default function CheckboxWithDescription() {
  return (
    <Field orientation="horizontal" className="max-w-sm">
      <Checkbox id="newsletter" defaultChecked />
      <FieldContent>
        <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
        <FieldDescription>One email a month. Unsubscribe at any time.</FieldDescription>
      </FieldContent>
    </Field>
  );
}
```

### States

Use `defaultChecked`, or `checked` with `onCheckedChange` to control it. `indeterminate` shows a
dash for a partial selection, and `aria-invalid` marks the checkbox as invalid.

```tsx
import { Checkbox } from "@/components/ui/checkbox";

export default function CheckboxStates() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Checkbox aria-label="Unchecked" />
      <Checkbox defaultChecked aria-label="Checked" />
      <Checkbox indeterminate aria-label="Indeterminate" />
      <Checkbox disabled aria-label="Disabled" />
      <Checkbox disabled defaultChecked aria-label="Disabled and checked" />
      <Checkbox aria-invalid aria-label="Invalid" />
    </div>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `Checkbox` | [`Checkbox.Root`](https://base-ui.com/react/components/checkbox#root) |

The tables leave out `className`, `style` and `render`. Parts built on Base UI take them as its [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides describe.

### Checkbox

| Prop               | Type                                                                         | Description                                                                                                                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nativeButton?`    | `boolean`                                                                    | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. Default: `false`                                                                                |
| `id?`              | `string`                                                                     | The id of the input element.                                                                                                                                                                                                                                 |
| `name?`            | `string`                                                                     | Identifies the field when a form is submitted. Default: `undefined`                                                                                                                                                                                          |
| `form?`            | `string`                                                                     | Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.                                                                                                                                                       |
| `checked?`         | `boolean`                                                                    | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead. Default: `undefined`                                                                                                                    |
| `defaultChecked?`  | `boolean`                                                                    | Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead. Default: `false`                                                                                                                                  |
| `disabled?`        | `boolean`                                                                    | Whether the component should ignore user interaction. Default: `false`                                                                                                                                                                                       |
| `onCheckedChange?` | `((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void)` | Event handler called when the checkbox is ticked or unticked.                                                                                                                                                                                                |
| `readOnly?`        | `boolean`                                                                    | Whether the user should be unable to tick or untick the checkbox. Default: `false`                                                                                                                                                                           |
| `required?`        | `boolean`                                                                    | Whether the user must tick the checkbox before submitting a form. Default: `false`                                                                                                                                                                           |
| `indeterminate?`   | `boolean`                                                                    | Whether the checkbox is in a mixed state: neither ticked, nor unticked. Default: `false`                                                                                                                                                                     |
| `inputRef?`        | `React.Ref<HTMLInputElement>`                                                | A ref to access the hidden `<input>` element.                                                                                                                                                                                                                |
| `parent?`          | `boolean`                                                                    | Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group). Default: `false`                                                                                         |
| `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". |