# Checkbox

```ts
import { Checkbox } from 'cx/widgets';
```



The `Checkbox` widget is used for expressing binary choices. It supports both standard styled checkboxes and native HTML checkboxes.

```tsx
import { createModel } from "cx/data";
import { bind, LabelsTopLayout } from "cx/ui";
import { Checkbox } from "cx/widgets";

interface Model {
  checked: boolean;
  indeterminate: boolean;
}

const m = createModel<Model>();

export default (
  <LabelsTopLayout columns={2}>
    <Checkbox label="Standard" value={bind(m.checked, true)} text="I agree to terms" />
    <Checkbox label="Native" value={m.checked} text="I agree to terms" native />
    <Checkbox label="Disabled" value={m.checked} text="I agree to terms" disabled />
    <Checkbox label="Read-only" value={m.checked} text="I agree to terms" readOnly />
    <Checkbox label="Required" value={m.checked} text="I agree to terms" required />
    <Checkbox label="Three State" value={m.indeterminate} text="Select all" indeterminate />
  </LabelsTopLayout>
);

```

## Three State Mode

Use the `indeterminate` prop to enable three-state mode. This displays a square icon when the value is `null` or `undefined`, which is useful for "select all" scenarios where only some items are selected.

## Configuration

### Core Properties

| Property        | Type      | Default | Description                                                    |
| --------------- | --------- | ------- | -------------------------------------------------------------- |
| `value`         | `boolean` | `false` | Checked state of the checkbox                                  |
| `checked`       | `boolean` |         | Alias for `value`                                              |
| `text`          | `string`  |         | Text displayed next to the checkbox                            |
| `label`         | `string`  |         | Label displayed before the checkbox                            |
| `disabled`      | `boolean` | `false` | Disables the checkbox                                          |
| `readOnly`      | `boolean` | `false` | Makes the checkbox read-only                                   |
| `required`      | `boolean` | `false` | Requires the checkbox to be checked                            |
| `indeterminate` | `boolean` | `false` | Enables three-state mode (checked, unchecked, indeterminate)   |
| `viewMode`      | `boolean` | `false` | Display as plain text instead of interactive checkbox          |
| `autoFocus`     | `boolean` | `false` | Automatically focus the field on mount                         |

### Appearance

| Property     | Type      | Default | Description                                        |
| ------------ | --------- | ------- | -------------------------------------------------- |
| `native`     | `boolean` | `false` | Use native HTML checkbox instead of styled version |
| `inputStyle` | `object`  |         | CSS styles for the checkbox element                |
| `viewText`   | `string`  |         | Text displayed in view mode                        |
| `emptyText`  | `string`  |         | Text shown in view mode when value is empty        |
| `tooltip`    | `string`  |         | Tooltip text or configuration                      |

### Behavior

| Property     | Type      | Default | Description                                              |
| ------------ | --------- | ------- | -------------------------------------------------------- |
| `unfocusable`| `boolean` | `false` | Disable focusing on the checkbox (useful in grids)       |

### Callbacks

| Property     | Type       | Description                                                                   |
| ------------ | ---------- | ----------------------------------------------------------------------------- |
| `onValidate` | `function` | Custom validation function returning error message or undefined |