{"slug":"checkbox","title":"Checkbox","description":"Using the checkbox machine in your project.","contentType":"component","framework":"svelte","content":"A checkbox allows users to make a binary choice, i.e. a choice between one of\ntwo possible mutually exclusive options.\n\n## Resources\n\n\n[Latest version: v1.39.1](https://www.npmjs.com/package/@zag-js/checkbox)\n[Logic Visualizer](https://zag-visualizer.vercel.app/checkbox)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/checkbox)\n\n\n\n**Features**\n\n- Tri-state checkbox (`indeterminate` state)\n- Syncs with `disabled` state of fieldset\n- Syncs with form `reset` events\n- Can be toggled programmatically\n\n## Installation\n\nInstall the checkbox package:\n\n```bash\nnpm install @zag-js/checkbox @zag-js/svelte\n# or\nyarn add @zag-js/checkbox @zag-js/svelte\n```\n\n## Anatomy\n\nCheck the checkbox anatomy and part names.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nImport the checkbox package:\n\n```tsx\nimport * as checkbox from \"@zag-js/checkbox\"\n```\n\nThe checkbox package exports two key functions:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\nThen use the framework integration helpers:\n\n```svelte\n<script lang=\"ts\">\n  import * as checkbox from \"@zag-js/checkbox\"\n  import { normalizeProps, useMachine } from \"@zag-js/svelte\"\n\n  const id = $props.id()\n  const service = useMachine(checkbox.machine, ({ id }))\n  const api = $derived(checkbox.connect(service, normalizeProps))\n</script>\n\n<label {...api.getRootProps()}>\n  <span {...api.getLabelProps()}>\n    Input is {api.checked ? \"checked\" : \"unchecked\"}\n  </span>\n  <div {...api.getControlProps()}></div>\n  <input {...api.getHiddenInputProps()} />\n</label>\n```\n\n### Setting the initial checked state\n\nSet `defaultChecked` to `true` to start checked.\n\n```tsx {2}\nconst service = useMachine(checkbox.machine, {\n  defaultChecked: true,\n})\n```\n\n### Indeterminate checkboxes\n\nSet `defaultChecked` or `checked` to `\"indeterminate\"` for a tri-state checkbox.\n\n```tsx {2}\nconst service = useMachine(checkbox.machine, {\n  defaultChecked: \"indeterminate\",\n})\n```\n\n### Controlled checkbox\n\nUse `checked` and `onCheckedChange` to control state externally.\n\n```svelte\n<script lang=\"ts\">\n  let checked = $state(false)\n\n  const service = useMachine(checkbox.machine, () => ({\n    checked,\n    onCheckedChange(details) {\n      checked = details.checked\n    },\n  }))\n</script>\n```\n\n### Disabling the checkbox\n\nSet `disabled` to `true` to prevent interaction.\n\n```tsx {2}\nconst service = useMachine(checkbox.machine, {\n  disabled: true,\n})\n```\n\n### Listening for changes\n\nWhen the checked state changes, `onCheckedChange` is invoked.\n\n```tsx {2-5}\nconst service = useMachine(checkbox.machine, {\n  onCheckedChange(details) {\n    // details => { checked: boolean | \"indeterminate\" }\n    console.log(\"checkbox is:\", details.checked)\n  },\n})\n```\n\n### Read-only checkbox\n\nSet `readOnly` to keep the checkbox focusable but prevent toggling.\n\n```tsx {2}\nconst service = useMachine(checkbox.machine, {\n  readOnly: true,\n})\n```\n\n### Usage within forms\n\nTo use checkbox within forms, set `name` and render `api.getHiddenInputProps()`.\n\n```tsx {2}\nconst service = useMachine(checkbox.machine, {\n  name: \"fruits\",\n})\n```\n\nNext, render the hidden input and ensure the value changes get propagated to the\nform correctly.\n\n```tsx\n<input {...api.getHiddenInputProps()} />\n```\n\n### Customizing submitted value\n\nSet `value` to customize the submitted form value when checked.\n\n```tsx\nconst service = useMachine(checkbox.machine, {\n  name: \"newsletter\",\n  value: \"subscribed\",\n})\n```\n\n### Associating with an external form\n\nIf the input belongs to a different form element, set `form`.\n\n```tsx\nconst service = useMachine(checkbox.machine, {\n  name: \"newsletter\",\n  form: \"settings-form\",\n})\n```\n\n## Styling guide\n\nEach part includes a `data-part` attribute you can target in CSS.\n\n### Checked state\n\nWhen the checkbox input is checked, the `data-state` attribute is added to the\nroot, control and label parts.\n\n```css\n[data-part=\"root\"][data-state=\"checked|unchecked|indeterminate\"] {\n  /* styles for when checkbox is checked */\n}\n\n[data-part=\"control\"][data-state=\"checked|unchecked|indeterminate\"] {\n  /* styles for when checkbox is checked */\n}\n\n[data-part=\"label\"][data-state=\"checked|unchecked|indeterminate\"] {\n  /* styles for when checkbox is checked */\n}\n```\n\n### Focused State\n\nWhen the checkbox input is focused, the `data-focus` attribute is added to the\nroot, control and label parts.\n\n```css\n[data-part=\"root\"][data-focus] {\n  /* styles for root focus state */\n}\n\n[data-part=\"control\"][data-focus] {\n  /* styles for control focus state */\n}\n\n[data-part=\"label\"][data-focus] {\n  /* styles for label focus state */\n}\n```\n\n### Disabled State\n\nWhen the checkbox is disabled, the `data-disabled` attribute is added to the\nroot, control and label parts.\n\n```css\n[data-part=\"root\"][data-disabled] {\n  /* styles for root disabled state */\n}\n\n[data-part=\"control\"][data-disabled] {\n  /* styles for control disabled state */\n}\n\n[data-part=\"label\"][data-disabled] {\n  /* styles for label disabled state */\n}\n```\n\n### Invalid State\n\nWhen the checkbox is invalid, the `data-invalid` attribute is added to the root,\ncontrol and label parts.\n\n```css\n[data-part=\"root\"][data-invalid] {\n  /* styles for root invalid state */\n}\n\n[data-part=\"control\"][data-invalid] {\n  /* styles for control invalid state */\n}\n\n[data-part=\"label\"][data-invalid] {\n  /* styles for label invalid state */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe checkbox machine exposes the following context properties:\n\n**`ids`**\nType: `Partial<{ root: string; hiddenInput: string; control: string; label: string; }>`\nDescription: The ids of the elements in the checkbox. Useful for composition.\n\n**`disabled`**\nType: `boolean`\nDescription: Whether the checkbox is disabled\n\n**`invalid`**\nType: `boolean`\nDescription: Whether the checkbox is invalid\n\n**`required`**\nType: `boolean`\nDescription: Whether the checkbox is required\n\n**`checked`**\nType: `CheckedState`\nDescription: The controlled checked state of the checkbox\n\n**`defaultChecked`**\nType: `CheckedState`\nDescription: The initial checked state of the checkbox when rendered.\nUse when you don't need to control the checked state of the checkbox.\n\n**`readOnly`**\nType: `boolean`\nDescription: Whether the checkbox is read-only\n\n**`onCheckedChange`**\nType: `(details: CheckedChangeDetails) => void`\nDescription: The callback invoked when the checked state changes.\n\n**`name`**\nType: `string`\nDescription: The name of the input field in a checkbox.\nUseful for form submission.\n\n**`form`**\nType: `string`\nDescription: The id of the form that the checkbox belongs to.\n\n**`value`**\nType: `string`\nDescription: The value of checkbox input. Useful for form submission.\n\n**`dir`**\nType: `\"ltr\" | \"rtl\"`\nDescription: The document's text/writing direction.\n\n**`id`**\nType: `string`\nDescription: The unique identifier of the machine.\n\n**`getRootNode`**\nType: `() => ShadowRoot | Node | Document`\nDescription: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.\n\n### Machine API\n\nThe checkbox `api` exposes the following methods:\n\n**`checked`**\nType: `boolean`\nDescription: Whether the checkbox is checked\n\n**`disabled`**\nType: `boolean`\nDescription: Whether the checkbox is disabled\n\n**`indeterminate`**\nType: `boolean`\nDescription: Whether the checkbox is indeterminate\n\n**`focused`**\nType: `boolean`\nDescription: Whether the checkbox is focused\n\n**`checkedState`**\nType: `CheckedState`\nDescription: The checked state of the checkbox\n\n**`setChecked`**\nType: `(checked: CheckedState) => void`\nDescription: Function to set the checked state of the checkbox\n\n**`toggleChecked`**\nType: `VoidFunction`\nDescription: Function to toggle the checked state of the checkbox\n\n### Data Attributes\n\n**`Root`**\n\n**`data-active`**: Present when active or pressed\n**`data-focus`**: Present when focused\n**`data-focus-visible`**: Present when focused with keyboard\n**`data-readonly`**: Present when read-only\n**`data-hover`**: Present when hovered\n**`data-disabled`**: Present when disabled\n**`data-state`**: \"indeterminate\" | \"checked\" | \"unchecked\"\n**`data-invalid`**: Present when invalid\n**`data-required`**: Present when required\n\n**`Label`**\n\n**`data-active`**: Present when active or pressed\n**`data-focus`**: Present when focused\n**`data-focus-visible`**: Present when focused with keyboard\n**`data-readonly`**: Present when read-only\n**`data-hover`**: Present when hovered\n**`data-disabled`**: Present when disabled\n**`data-state`**: \"indeterminate\" | \"checked\" | \"unchecked\"\n**`data-invalid`**: Present when invalid\n**`data-required`**: Present when required\n\n**`Control`**\n\n**`data-active`**: Present when active or pressed\n**`data-focus`**: Present when focused\n**`data-focus-visible`**: Present when focused with keyboard\n**`data-readonly`**: Present when read-only\n**`data-hover`**: Present when hovered\n**`data-disabled`**: Present when disabled\n**`data-state`**: \"indeterminate\" | \"checked\" | \"unchecked\"\n**`data-invalid`**: Present when invalid\n**`data-required`**: Present when required\n\n**`Indicator`**\n\n**`data-active`**: Present when active or pressed\n**`data-focus`**: Present when focused\n**`data-focus-visible`**: Present when focused with keyboard\n**`data-readonly`**: Present when read-only\n**`data-hover`**: Present when hovered\n**`data-disabled`**: Present when disabled\n**`data-state`**: \"indeterminate\" | \"checked\" | \"unchecked\"\n**`data-invalid`**: Present when invalid\n**`data-required`**: Present when required\n\n## Accessibility\n\n### Keyboard Interactions\n\n**`Space`**\nDescription: Toggle the checkbox","package":"@zag-js/checkbox","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/checkbox.mdx"}