# or
yarn add @zag-js/checkbox @zag-js/svelte
```

## Anatomy

To set up the checkbox correctly, you'll need to understand its anatomy and how
we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Usage

First, import the checkbox package into your project

```jsx
import * as checkbox from "@zag-js/checkbox"
```

The checkbox package exports two key functions:

- `machine` â The state machine logic for the checkbox widget.
- `connect` â The function that translates the machine's state to JSX attributes
  and event handlers.

Next, import the required hooks and functions for your framework and use the
checkbox machine in your project ð¥

```svelte
<script lang="ts">
  import * as checkbox from "@zag-js/checkbox"
  import { normalizeProps, useMachine } from "@zag-js/svelte"

  const id = $props.id()
  const service = useMachine(checkbox.machine, ({ id }))
  const api = $derived(checkbox.connect(service, normalizeProps))
</script>

<label {...api.getRootProps()}>
  <span {...api.getLabelProps()}>
    Input is {api.checked ? "checked" : "unchecked"}
  </span>
  <div {...api.getControlProps()}></div>
  <input {...api.getHiddenInputProps()} />
</label>
```

### Setting the initial checked state

To make a checkbox checked by default, set the context's `defaultChecked`
property to `true`

```jsx {2}
const service = useMachine(checkbox.machine, {
  defaultChecked: true,
})
```

### Indeterminate checkboxes

To make a checkbox indeterminate, set the `defaultChecked` or `checked` property
to `"indeterminate"`

```jsx {2}
const service = useMachine(checkbox.machine, {
  defaultChecked: "indeterminate",
})
```

### Controlled checkbox

To control the checked state programmatically, pass the `checked` and
`onCheckedChange` properties to the machine function.

```svelte
<script lang="ts">
  let checked = $state(false)

  const service = useMachine(checkbox.machine, () => ({
    checked,
    onCheckedChange(details) {
      checked = details.checked
    },
  }))
</script>
```

### Disabling the checkbox

To make a checkbox disabled, set the context's `disabled` property to true

```jsx {2}
const service = useMachine(checkbox.machine, {
  disabled: true,
})
```

### Listening for changes

When the checkbox value changes, the `onCheckChange` callback is invoked.

```jsx {2-5}
const service = useMachine(checkbox.machine, {
  onCheckChange(details) {
    // details => { checked: boolean }
    console.log("checkbox is:", details.checked)
  },
})
```

### Usage within forms

To use checkbox within forms, use the exposed `api.getHiddenInputProps()` from
the `connect` function and ensure you pass `name` value to the machine's
context.

```jsx {2}
const service = useMachine(checkbox.machine, {
  name: "fruits",
})
```

Next, render the hidden input and ensure the value changes get propagated to the
form correctly.

```jsx
<input {...api.getHiddenInputProps()} />
```

## Styling guide

Earlier, we mentioned that each checkbox part has a `data-part` attribute added
to them to select and style them in the DOM.

### Checked state

When the checkbox input is checked, the `data-state` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-state="checked|unchecked|indeterminate"] {
  /* styles for when checkbox is checked */
}

[data-part="control"][data-state="checked|unchecked|indeterminate"] {
  /* styles for when checkbox is checked */
}

[data-part="label"][data-state="checked|unchecked|indeterminate"] {
  /* styles for when checkbox is checked */
}
```

### Focused State

When the checkbox input is focused, the `data-focus` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="label"][data-focus] {
  /* styles for label focus state */
}
```

### Disabled State

When the checkbox is disabled, the `data-disabled` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}
```

### Invalid State

When the checkbox is invalid, the `data-invalid` attribute is added to the root,
control and label parts.

```css
[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}
```

## Methods and Properties

### Machine Context

The checkbox machine exposes the following context properties:

**`ids`**
Type: `Partial<{ root: string; hiddenInput: string; control: string; label: string; }>`
Description: The ids of the elements in the checkbox. Useful for composition.

**`disabled`**
Type: `boolean`
Description: Whether the checkbox is disabled

**`invalid`**
Type: `boolean`
Description: Whether the checkbox is invalid

**`required`**
Type: `boolean`
Description: Whether the checkbox is required

**`checked`**
Type: `CheckedState`
Description: The controlled checked state of the checkbox

**`defaultChecked`**
Type: `CheckedState`
Description: The initial checked state of the checkbox when rendered.
Use when you don't need to control the checked state of the checkbox.

**`readOnly`**
Type: `boolean`
Description: Whether the checkbox is read-only

**`onCheckedChange`**
Type: `(details: CheckedChangeDetails) => void`
Description: The callback invoked when the checked state changes.

**`name`**
Type: `string`
Description: The name of the input field in a checkbox.
Useful for form submission.

**`form`**
Type: `string`
Description: The id of the form that the checkbox belongs to.

**`value`**
Type: `string`
Description: The value of checkbox input. Useful for form submission.

**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.

**`id`**
Type: `string`
Description: The unique identifier of the machine.

**`getRootNode`**
Type: `() => ShadowRoot | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

### Machine API

The checkbox `api` exposes the following methods:

**`checked`**
Type: `boolean`
Description: Whether the checkbox is checked

**`disabled`**
Type: `boolean`
Description: Whether the checkbox is disabled

**`indeterminate`**
Type: `boolean`
Description: Whether the checkbox is indeterminate

**`focused`**
Type: `boolean`
Description: Whether the checkbox is focused

**`checkedState`**
Type: `CheckedState`
Description: The checked state of the checkbox

**`setChecked`**
Type: `(checked: CheckedState) => void`
Description: Function to set the checked state of the checkbox

**`toggleChecked`**
Type: `VoidFunction`
Description: Function to toggle the checked state of the checkbox

### Data Attributes

**`Root`**

**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Label`**

**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Control`**

**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

**`Indicator`**

**`data-active`**: Present when active or pressed
**`data-focus`**: Present when focused
**`data-focus-visible`**: Present when focused with keyboard
**`data-readonly`**: Present when read-only
**`data-hover`**: Present when hovered
**`data-disabled`**: Present when disabled
**`data-state`**: "indeterminate" | "checked" | "unchecked"
**`data-invalid`**: Present when invalid
**`data-required`**: Present when required

## Accessibility

### Keyboard Interactions

**`Space`**
Description: Toggle the checkbox
The clipboard machine allows users to quickly copy content to clipboard.

## Resources


[Latest version: v1.33.1](https://www.npmjs.com/package/@zag-js/clipboard)
[Logic Visualizer](https://zag-visualizer.vercel.app/clipboard)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/clipboard)



## Installation

To use the clipboard machine in your project, run the following command in your
command line:

```bash
npm install @zag-js/clipboard @zag-js/svelte