Checkbox Group

A group of checkboxes for selecting multiple values.

Select options: Option 1 Option 2 Option 3

<f:variable name="items" value="{
    0: { value: 'option1', text: 'Option 1' },
    1: { value: 'option2', text: 'Option 2' },
    2: { value: 'option3', text: 'Option 3' }
}" />

<ui:checkboxGroup.root name="options[]">
    <ui:checkboxGroup.label>Select options:</ui:checkboxGroup.label>
    <f:for each="{items}" as="item">
        <ui:checkbox.root value="{item.value}">
            <ui:checkbox.control />
            <ui:checkbox.label>{item.text}</ui:checkbox.label>
        </ui:checkbox.root>
    </f:for>
</ui:checkboxGroup.root>

Features

Selects several values at once
Optional limit on the selection with maxSelectedValues
Full keyboard navigation support
Syncs with native inputs for form submission
Works with the Field component

Anatomy

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

Installation

typo3 ui:add checkboxGroup

Read more about installing Components and Primitives.

Examples

Default checked

Pass the values to preselect as a list in defaultValue. The notification preferences start with email and push checked.

Notification preferences: Email notifications SMS notifications Push notifications

<f:variable name="items" value="{
    0: { value: 'email', text: 'Email notifications' },
    1: { value: 'sms', text: 'SMS notifications' },
    2: { value: 'push', text: 'Push notifications' }
}" />

<ui:checkboxGroup.root name="notifications[]" defaultValue="{0: 'email', 1: 'push'}">
    <ui:checkboxGroup.label>Notification preferences:</ui:checkboxGroup.label>
    <f:for each="{items}" as="item">
        <ui:checkbox.root value="{item.value}">
            <ui:checkbox.control />
            <ui:checkbox.label>{item.text}</ui:checkbox.label>
        </ui:checkbox.root>
    </f:for>
</ui:checkboxGroup.root>

Disabled items

Set disabled on a single checkbox.root to lock that option while the others stay interactive.

Select plans: Basic Plan Premium Plan (Unavailable) Enterprise Plan

<ui:checkboxGroup.root name="plans[]" defaultValue="{0: 'basic'}">
    <ui:checkboxGroup.label>Select plans:</ui:checkboxGroup.label>
    <ui:checkbox.root value="basic">
        <ui:checkbox.control />
        <ui:checkbox.label>Basic Plan</ui:checkbox.label>
    </ui:checkbox.root>
    <ui:checkbox.root value="premium" disabled="{true}">
        <ui:checkbox.control />
        <ui:checkbox.label>Premium Plan (Unavailable)</ui:checkbox.label>
    </ui:checkbox.root>
    <ui:checkbox.root value="enterprise">
        <ui:checkbox.control />
        <ui:checkbox.label>Enterprise Plan</ui:checkbox.label>
    </ui:checkbox.root>
</ui:checkboxGroup.root>

Disabled group

Set disabled on checkboxGroup.root to lock every option at once.

Select features: Feature 1 Feature 2 Feature 3

<ui:checkboxGroup.root name="features[]" disabled="{true}">
    <ui:checkboxGroup.label>Select features:</ui:checkboxGroup.label>
    <ui:checkbox.root value="feature1">
        <ui:checkbox.control />
        <ui:checkbox.label>Feature 1</ui:checkbox.label>
    </ui:checkbox.root>
    <ui:checkbox.root value="feature2">
        <ui:checkbox.control />
        <ui:checkbox.label>Feature 2</ui:checkbox.label>
    </ui:checkbox.root>
    <ui:checkbox.root value="feature3">
        <ui:checkbox.control />
        <ui:checkbox.label>Feature 3</ui:checkbox.label>
    </ui:checkbox.root>
</ui:checkboxGroup.root>

Maximum selections

Set maxSelectedValues to cap the selection. Pick two colors in the demo and the remaining one is disabled until you uncheck another.

Pick up to 2 colors: Red Green Blue

<f:variable name="items" value="{
    0: { value: 'red', text: 'Red' },
    1: { value: 'green', text: 'Green' },
    2: { value: 'blue', text: 'Blue' }
}" />

<ui:checkboxGroup.root name="colors[]" maxSelectedValues="2" defaultValue="{0: 'red'}">
    <ui:checkboxGroup.label>Pick up to 2 colors:</ui:checkboxGroup.label>
    <f:for each="{items}" as="item">
        <ui:checkbox.root value="{item.value}">
            <ui:checkbox.control />
            <ui:checkbox.label>{item.text}</ui:checkbox.label>
        </ui:checkbox.root>
    </f:for>
</ui:checkboxGroup.root>

Select all

A checkbox above the group checks or clears every option, and shows the indeterminate state while only some are checked. The entry file tab shows how the two are wired.

All User Permissions

View Dashboard Access Reports Modify Settings

<ui:exposeToClient />

<div class="space-y-3">
    <ui:checkbox.root value="all" autoMount="{false}" rootId="select-all" defaultChecked="indeterminate">
        <ui:checkbox.control />
        <ui:checkbox.label>All User Permissions</ui:checkbox.label>
    </ui:checkbox.root>

    <ui:checkboxGroup.root name="permissions[]" defaultValue="{0: 'reports'}" autoMount="{false}" rootId="select-all-group" class="ms-4" aria-label="User Permissions">
        <f:for each="{context.items}" as="item">
            <ui:checkbox.root value="{item.value}">
                <ui:checkbox.control />
                <ui:checkbox.label>{item.text}</ui:checkbox.label>
            </ui:checkbox.root>
        </f:for>
    </ui:checkboxGroup.root>
</div>

<vite:asset entry="EXT:docs/Resources/Private/Components/ui/CheckboxGroupExamples/SelectAll.entry.ts" />

import { mount, mountAll } from 'fluid-primitives';
import { Checkbox } from 'fluid-primitives/checkbox';
import { CheckboxGroup } from 'fluid-primitives/checkbox-group';

mountAll('ui:checkboxGroupExamples.selectAll', ({ props }) => {
    const allValues = props.items.map(item => item.value);

    let group: CheckboxGroup | undefined;
    let selectAllCheckbox: Checkbox | undefined;

    group = mount('ui:checkboxGroup', 'select-all-group', ({ props }) => {
        const instance = new CheckboxGroup({
            ...props,
            onValueChange: details => {
                const value = details.value;
                const allSelected = value.length === allValues.length && allValues.length > 0;
                const noneSelected = value.length === 0;

                instance.updateProps({ value });

                if (noneSelected) {
                    selectAllCheckbox?.updateProps({ checked: false });
                    return;
                }

                if (allSelected) {
                    selectAllCheckbox?.updateProps({ checked: true });
                    return;
                }

                selectAllCheckbox?.updateProps({ checked: 'indeterminate' });
            },
        });
        instance.init();
        return instance;
    });

    selectAllCheckbox = mount('ui:checkbox', 'select-all', ({ props }) => {
        const instance = new Checkbox({
            ...props,
            onCheckedChange: ({ checked }) => {
                instance.updateProps({ checked });
                group?.updateProps({ value: checked ? allValues : [] });
            },
        });
        instance.init();
        return instance;
    });
});

API Reference

The following tables cover the available props of the Fluid Primitives.

checkboxGroup.root

Provides shared state for a group of related checkboxes. Renders a <div> element.

Name	Description	Required	Default
`defaultValue`	`string[]` The initial value of the checkbox group. Use when you don't need to control the value of the checkbox group. Inherited from a surrounding field when available.	No	-
`name`	`string` The name of the input fields in the checkbox group. Useful for form submission. Inherited from a surrounding field when available.	No	-
`form`	`string` The form id the checkbox group belongs to.	No	-
`disabled`	`boolean` If true, the checkbox group is disabled. Inherited from a surrounding field when available.	No	-
`readOnly`	`boolean` If true, the checkbox group is read-only. Inherited from a surrounding field when available.	No	-
`required`	`boolean` If true, the checkbox group is required. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` If true, the checkbox group is invalid. Inherited from a surrounding field when available.	No	-
`maxSelectedValues`	`integer` The maximum number of selected values.	No	-
`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-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-invalid`	Present when invalid

checkboxGroup.label

Labels the checkbox group. 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-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-invalid`	Present when invalid

Machine options

Name	Description	Default
`id`	`string` The unique identifier of the checkbox group.	-
`ids`	`Record<string, string> \| undefined` The ids of the elements in the checkbox group. Useful for composition.	-
`defaultValue`	`string[] \| undefined` The initial value of the checkbox group (uncontrolled)	-
`value`	`string[] \| undefined` The controlled value of the checkbox group	-
`name`	`string \| undefined` The name of the input fields in the checkbox group (for form submission)	-
`form`	`string \| undefined` The form id the checkbox group belongs to	-
`disabled`	`boolean \| undefined` If true, the checkbox group is disabled	-
`readOnly`	`boolean \| undefined` If true, the checkbox group is read-only	-
`required`	`boolean \| undefined` If true, the checkbox group is required	-
`invalid`	`boolean \| undefined` If true, the checkbox group is invalid	-
`maxSelectedValues`	`number \| undefined` The maximum number of selected values	-
`onValueChange`	`((details: { value: string[] }) => void) \| undefined` Called when the value changes	-

Machine JavaScript API

Name	Type	Description
`value`	`string[]`	The current value of the checkbox group
`name`	`string \| undefined`	The name for form submission
`disabled`	`boolean`	Whether the checkbox group is disabled
`readOnly`	`boolean`	Whether the checkbox group is read-only
`invalid`	`boolean`	Whether the checkbox group is invalid
`isChecked`	`(value: string) => boolean`	Check if a value is selected
`setValue`	`(value: string[]) => void`	Set the entire value array
`addValue`	`(value: string) => void`	Add a value to the selection
`removeValue`	`(value: string) => void`	Remove a value from the selection
`toggleValue`	`(value: string) => void`	Toggle a value
`getItemProps`	`(props: CheckboxGroupItemProps) => CheckboxGroupItemState`	Get props to merge into a checkbox item