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

Multiple selection support (unlike RadioGroup which is single selection)
Optional maximum number of selections via maxSelectedValues
Full keyboard navigation support
Syncs with native form elements for proper form submission
Works with Field component for form integration

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 checkbox-group

Read more about installing Components and Primitives.

Examples

Default Checked

Pre-select multiple options using an array of values.

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

Disable specific checkbox options.

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

Disable the entire checkbox group.

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

Limit the number of selectable options. Once the limit is reached, remaining unchecked options are automatically disabled.

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

Implement a "Select All" checkbox that toggles all options.

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

Checkbox Group

Features

Anatomy

Installation

Examples

Default Checked

Disabled Items

Disabled Group

Maximum Selections

Select All

API Reference

checkboxGroup.root

Rendered data attributes

checkboxGroup.label

Rendered data attributes

Machine options

Machine JavaScript API

On this page