# Checkbox

**An easily stylable checkbox component.**

**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/Checkbox) · [Zag.js Docs](https://zagjs.com/components/react/checkbox)

**Checkbox.html**

```html
<ui:checkbox.root>
    <ui:checkbox.control />
    <ui:checkbox.label>Enable notifications</ui:checkbox.label>
</ui:checkbox.root>
```

**Checkbox.ts**

```ts
import { mountAll } from 'fluid-primitives';
import { Checkbox } from 'fluid-primitives/checkbox';

mountAll('checkbox', ({ props }) => {
    const checkbox = new Checkbox(props);
    checkbox.init();
    return checkbox;
});

```

## Features

- Tri-state support (checked, unchecked, indeterminate)
- Syncs with native form elements for proper form submission
- Works with Field component for form integration
- Full keyboard support

## Installation

```bash
typo3 ui:add checkbox
```

Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives.com/tree/main/packages/docs/Resources/Private/Registry/Checkbox) into your project.

Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).

## Examples

### Default Checked

Set the checkbox to be checked by default.

**Checkbox.html**

```html
<ui:checkbox.root defaultChecked="{true}">
    <ui:checkbox.control />
    <ui:checkbox.label>Checked by default</ui:checkbox.label>
</ui:checkbox.root>

```

### Indeterminate State

Use the indeterminate state for "select all" checkboxes or partial selections.

**Checkbox.html**

```html
<ui:checkbox.root defaultChecked="indeterminate">
    <ui:checkbox.control />
    <ui:checkbox.label>Select all (some selected)</ui:checkbox.label>
</ui:checkbox.root>

```

### Disabled

Prevent interaction with the checkbox.

**Checkbox.html**

```html
<ui:checkbox.root disabled="{true}">
    <ui:checkbox.control />
    <ui:checkbox.label>Disabled checkbox</ui:checkbox.label>
</ui:checkbox.root>

```

## API Reference

### checkbox.root

Groups the checkbox control, label, and input into one interactive label. Renders a `<label>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean` | No | `-` | Whether the checkbox is disabled. Inherited from a surrounding field when available. |
| `invalid` | `boolean` | No | `-` | Whether the checkbox is invalid. Inherited from a surrounding field when available. |
| `required` | `boolean` | No | `-` | Whether the checkbox is required. Inherited from a surrounding field when available. |
| `defaultChecked` | `mixed` | No | `false` | The initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox. |
| `name` | `string` | No | `-` | The name of the input field in the checkbox. Useful for form submission. Inherited from a surrounding field when available. |
| `form` | `string` | No | `-` | The id of the form that the checkbox belongs to. |
| `readOnly` | `boolean` | No | `-` | Whether the checkbox is read-only. Inherited from a surrounding field when available. |
| `value` | `string` | No | `1` | The value of checkbox input. Useful for form submission. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. |
| `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. |
| `controlled` | `boolean` | No | `false` | If true, the component is meant to be initialized manually inside another component |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `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 |

### checkbox.hiddenInput

Provides the native checkbox input for form submission and browser integration. Renders an `<input>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

### checkbox.control

Displays the visual checkbox box that reflects the checked state. Renders a `<div>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `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 |

### checkbox.indicator

Displays the checked or indeterminate indicator inside the control. Renders a `<div>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `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 |

### checkbox.label

Displays the visible label text for the checkbox. Renders a `<span>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `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 |

### Machine JavaScript API

| Name | Type | Description |
| --- | --- | --- |
| `checked` | `boolean` | Whether the checkbox is checked |
| `disabled` | `boolean \| undefined` | Whether the checkbox is disabled |
| `indeterminate` | `boolean` | Whether the checkbox is indeterminate |
| `focused` | `boolean \| undefined` | Whether the checkbox is focused |
| `checkedState` | `CheckedState` | The checked state of the checkbox |
| `setChecked` | `(checked: CheckedState) => void` | Function to set the checked state of the checkbox |
| `toggleChecked` | `VoidFunction` | Function to toggle the checked state of the checkbox |

### Accessibility

| Key | Description |
| --- | --- |
| `Space`  | Toggle the checkbox |

## Anatomy

```html
<primitives:checkbox.root>
    <primitives:checkbox.control>
        <primitives:checkbox.indicator />
    </primitives:checkbox.control>
    <primitives:checkbox.label />
    <primitives:checkbox.hiddenInput />
</primitives:checkbox.root>
```