{
  "title": "Checkbox",
  "description": "Controlled or uncontrolled checkbox with indeterminate support and asChild.",
  "url": "/docs/components/checkbox",
  "since": "0.1.0",
  "tags": [
    "control",
    "form"
  ],
  "platform": "both",
  "source": "---\ntitle: Checkbox\ndescription: Controlled or uncontrolled checkbox with indeterminate support and asChild.\nsince: 0.1.0\ntags: [control, form]\nplatform: both\ncategory: controls\n---\n\nimport { BundleSize } from '@/components/bundle-size';\nimport { ExpoSnack } from '@/components/expo-snack';\nimport { Preview } from '@/components/preview';\nimport { PropsTable } from '@/components/props-table';\n\n<BundleSize component=\"Checkbox\" />\n\n## At a glance\n\n- Resolves the check icon through `SemanticIconsProvider` (key: `checkmark`).\n- Forwards every `Pressable` prop, plus `asChild` for custom roots.\n\n## Preview\n\n<Preview name=\"checkbox-basic\" />\n\n## `checked` and `defaultChecked`\n\nControlled mode: pass `checked` and pair with `onChange`. Uncontrolled\nmode: pass `defaultChecked` and let the Checkbox track state itself.\nMixing the two — passing both `checked` and `defaultChecked` — picks\ncontrolled and ignores `defaultChecked` (with a warning in dev).\n\n```tsx\n// Controlled\nconst [done, setDone] = useState(false);\n<Checkbox checked={done} onChange={setDone} label=\"Mark complete\" />\n\n// Uncontrolled\n<Checkbox defaultChecked label=\"Send weekly digest\" />\n```\n\n## `indeterminate`\n\nA controlled-only third state for \"some but not all children checked\".\nRender a parent `Checkbox` with `indeterminate={true}` when its children\nhave a mixed selection, and let it flip back to `checked` /\n`!checked` when the user toggles the parent.\n\n<Preview name=\"checkbox-indeterminate\" />\n\n## `label`\n\nRenders a clickable label next to the box. Pressing the label toggles\nthe Checkbox — same target as the box itself, with a wider hit area\nthat's friendlier on touch.\n\n```tsx\n<Checkbox label=\"I accept the terms\" />\n```\n\nWhen you need richer label content (a link inside the label, an icon),\npass `children` instead — the Checkbox treats the children as the\nlabel slot.\n\n## Inline label vs Field\n\nThe `label` prop is the **inline** label (right of the box) — the control's own affordance.\nUse it for stand-alone checkboxes:\n\n```tsx\nimport { Checkbox } from '@nori-ui/core';\n\nexport const Example = () => (\n    <Checkbox label=\"I accept the terms\" />\n);\n```\n\nFor grouped settings with description and error, wrap in `<Field>`:\n\n```tsx\nimport { Checkbox, Field } from '@nori-ui/core';\n\nexport const Example = () => (\n    <Field label=\"Notifications\" description=\"Choose how you'd like to be notified.\">\n        <Checkbox label=\"Send me email updates\" />\n    </Field>\n);\n```\n\nSee [Field](/docs/components/field) for the full API. For custom layouts, use the [compound API](/docs/components/field#custom-layout-compound-api).\n\n## `disabled`\n\nGreys out the box and blocks `onChange`. Forwarded as\n`aria-disabled` so screen readers announce the state.\n\n```tsx\n<Checkbox disabled label=\"Locked option\" />\n```\n\n## `onChange`\n\nFires with the next boolean checked value (or `false` when leaving\nindeterminate via toggle). Pair with `checked` for controlled, omit\nfor uncontrolled — the Checkbox calls it either way so you can react\nto the user's input.\n\n```tsx\n<Checkbox onChange={(next) => analytics.track('opt-in', { next })} />\n```\n\n## `asChild`\n\nRenders a supplied element as the interactive root. Useful when wrapping\nthe entire row of label + helper text in a single press target.\n\n```tsx\n<Checkbox asChild>\n    <Pressable>\n        <YourCustomRow />\n    </Pressable>\n</Checkbox>\n```\n\n## Accessibility props\n\nWhen wrapping `Checkbox` in `<Field>`, the following ARIA and accessibility\nattributes are injected onto the underlying `Pressable` automatically:\n\n- `id` — matches the `htmlFor` of the label; generated by `Field`.\n- `aria-labelledby` — references the `Field.Label` element's ID.\n- `aria-describedby` — references `Field.Description` and/or `Field.Error` IDs when present.\n- `aria-invalid` — set when the enclosing `Field` has a non-null `error`.\n- `aria-required` — set when the enclosing `Field` has `required={true}`.\n\nOn native, the React Native counterparts are forwarded instead:\n`accessibilityLabelledBy` (mirrors `aria-labelledby`) and\n`accessibilityDescribedBy` (mirrors `aria-describedby`).\n\nYou can also pass any of these props explicitly when using `Checkbox` outside a\n`Field`, e.g., `<Checkbox aria-label=\"Accept terms\" />`.\n\n## Native preview\n\n<ExpoSnack component=\"Checkbox\" height={300} />\n\n## Props\n\n<PropsTable component=\"Checkbox\" />\n"
}