# Checkbox A labeled checkbox on the Field contract, with the label to its right: pass `label`, and `checked` with `onCheckedChange` (or `defaultChecked`). Clicking the label toggles it, Space toggles it from the keyboard, the box fills and the tick draws, and `indeterminate` shows a dash announced as "mixed". With `name`, a checked box submits `name=value` with its form. ```tsx import { Checkbox } from "@/components/ouro/checkbox/checkbox"; ``` ## Example ```tsx ``` ## Use instead when - Use `CheckboxGroup` instead for several choices under one legend that submit together, `Switch` for a setting that applies at once, and `RadioGroup` when only one choice may be picked. ## Props Type: `CheckboxProps`. | Prop | Type | Description | | --- | --- | --- | | `checked` | `boolean` | Whether it is checked, for a controlled checkbox; pair it with `onCheckedChange`. | | `className` | `string` | Layout only: margins, width, grid placement (`mt-4`, `col-span-2`). Appearance classes warn in development; style checkboxes in your theme. | | `defaultChecked` | `boolean` | Whether it starts checked, for an uncontrolled checkbox. | | `description` | `ReactNode` | Supporting text under the label, read after it through `aria-describedby`. | | `disabled` | `boolean` | Disables the checkbox and fades it. | | `error` | `ReadonlyErrorMessages` | What is wrong, from your server action or client check, shown under the label; the box gets `aria-invalid`. A message is text or a React node (one with a link); an empty string or array means valid. In a `CheckboxGroup`, pass it to the group. | | `hideLabel` | `boolean` | Hides the label visually; screen readers still read it as the checkbox's name. | | `indeterminate` | `boolean` | Shows a dash and announces "mixed": neither checked nor unchecked, as a "select all" box does when some of its items are checked. It is controlled: a click does not clear it, so clear it in `onCheckedChange`, as in ``. The box submits only while `checked`. | | `label` (required) | `string` | What checking it means, shown to the right of the box and read as its name. Required: every control needs a name. To hide it visually, keep it and add `hideLabel`. | | `name` | `string` | The form field name it submits under when checked. In a `CheckboxGroup`, the group's `name` applies. | | `onCheckedChange` | `((checked: boolean) => void)` | Called with the new state when it is checked or unchecked. | | `readOnly` | `boolean` | Shows the state but ignores clicks and keys, unlike `disabled`, which also fades it. | | `ref` | `Ref` | The box element, a ``. | | `required` | `boolean` | The box must be checked to submit the form (accepting terms): it gets `required` and `aria-required`, and the label a marker. In a `CheckboxGroup`, pass it to the group. | | `value` | `string` | What a checked box submits (`on` without one). In a `CheckboxGroup`, it identifies the box in the group's `value`, so it is required there. | ## Don't use These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix. - `defaultValue`: Not a prop. A checkbox's starting state is `defaultChecked`: ``. - `errorMessage`: Not a prop. Ouro UI uses `error`: ``. - `helperText`: Not a prop. Ouro UI uses `description`: ``. - `invalid`: Not a prop. `error` marks the checkbox invalid: ``. - `isChecked`: Not a prop. Ouro UI uses `checked`: ``. - `isDisabled`: Not a prop. Ouro UI uses `disabled`: ``. - `isIndeterminate`: Not a prop. Ouro UI uses `indeterminate`: ``. - `isInvalid`: Not a prop. `error` marks the checkbox invalid: ``. - `isRequired`: Not a prop. Ouro UI uses `required`: ``. - `onChange`: Not a prop. Ouro UI uses `onCheckedChange`, which gets the new state: `onCheckedChange={setChecked}`. ## `className` is for layout only Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn. Alignment classes (`text-center`) warn too: set alignment on a parent element. ## Types ### `ErrorMessage` One error message: text, or a React element for a message that carries a link or other markup. ```ts type ErrorMessage = string | ReactElement; ``` ### `ReadonlyErrorMessages` A read-only message view accepted by fields and Form; mutable input arrays remain valid. ```ts type ReadonlyErrorMessages = ErrorMessage | readonly ErrorMessage[]; ```