Checkbox
View as MarkdownAn easily stylable checkbox component.
<ui:checkbox.root>
<ui:checkbox.control />
<ui:checkbox.label>Enable notifications</ui:checkbox.label>
</ui:checkbox.root>
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
typo3 ui:add checkbox
Please copy the files manually from GitHub into your project.
Read more about installing Components and Primitives.
Examples
Default Checked
Set the checkbox to be checked by default.
<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.
<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.
<ui:checkbox.root disabled="{true}">
<ui:checkbox.control />
<ui:checkbox.label>Disabled checkbox</ui:checkbox.label>
</ui:checkbox.root>
API Reference
The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.
checkbox.root
Groups the checkbox control, label, and input into one interactive label. Renders a <label> element.
| Name | Description | Required | Default |
|---|---|---|---|
disabled | booleanWhether the checkbox is disabled. Inherited from a surrounding field when available. | No | - |
invalid | booleanWhether the checkbox is invalid. Inherited from a surrounding field when available. | No | - |
required | booleanWhether the checkbox is required. Inherited from a surrounding field when available. | No | - |
defaultChecked | mixedThe initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox. | No | false |
name | stringThe name of the input field in the checkbox. Useful for form submission. Inherited from a surrounding field when available. | No | - |
form | stringThe id of the form that the checkbox belongs to. | No | - |
readOnly | booleanWhether the checkbox is read-only. Inherited from a surrounding field when available. | No | - |
value | stringThe value of checkbox input. Useful for form submission. | No | 1 |
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
rootId | stringThe root ID of the component, used for hydration and identification. | No | - |
ids | arrayThe IDs of of the component parts for composition. | No | [] |
controlled | booleanIf true, the component is meant to be initialized manually inside another component | No | false |
class | stringThe CSS class(es) to be applied to the component. | No | - |
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
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 | Description | Required | Default |
|---|---|---|---|
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
checkbox.control
Displays the visual checkbox box that reflects the checked state. Renders a <div> element.
| Name | Description | Required | Default |
|---|---|---|---|
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
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 | Description | Required | Default |
|---|---|---|---|
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
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 | Description | Required | Default |
|---|---|---|---|
asChild | booleanIf true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | No | - |
class | stringThe CSS class(es) to be applied to the component. | No | - |
attributes | arrayAdditional attributes that should be rendered on the component where ui:attributes is used. | No | [] |
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
<primitives:checkbox.root>
<primitives:checkbox.control>
<primitives:checkbox.indicator />
</primitives:checkbox.control>
<primitives:checkbox.label />
<primitives:checkbox.hiddenInput />
</primitives:checkbox.root>