Checkbox

A checkbox with a checked, unchecked and indeterminate state.

Enable notifications

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

Features

Tri-state support (checked, unchecked, indeterminate)
Syncs with a native input for form submission
Works with the Field component
Full keyboard support

Anatomy

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

Installation

typo3 ui:add checkbox

Read more about installing Components and Primitives.

Examples

Default checked

Pass defaultChecked="{true}" to render the checkbox checked.

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

Pass defaultChecked="indeterminate" for a "select all" checkbox while only some of its options are selected.

Select all (some selected)

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

Disabled

Pass disabled="{true}" to block interaction with the checkbox.

Disabled 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`	`boolean` Whether the checkbox is disabled. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` Whether the checkbox is invalid. Inherited from a surrounding field when available.	No	-
`required`	`boolean` Whether the checkbox is required. Inherited from a surrounding field when available.	No	-
`defaultChecked`	`mixed` The 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`	`string` The name of the input field in the checkbox. Useful for form submission. Inherited from a surrounding field when available.	No	-
`form`	`string` The id of the form that the checkbox belongs to.	No	-
`readOnly`	`boolean` Whether the checkbox is read-only. Inherited from a surrounding field when available.	No	-
`value`	`string` The value of checkbox input. Useful for form submission.	No	1
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-checkbox-root`	<uid>
`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, with the empty-value input that submits '' while the box is unchecked in front of it.

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

checkbox.control

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

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

Rendered data attributes

Attribute	Description
`data-checkbox-control`	<uid>
`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
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-checkbox-indicator`	<uid>
`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
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-checkbox-label`	<uid>
`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
`getRootState`	`() => RootState`	Returns the state of the checkbox

Accessibility

Key	Description
`Space`	Toggle the checkbox