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>

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

mount('checkbox-group', ({ props }) => {
    const checkboxGroup = new CheckboxGroup(props);
    checkboxGroup.init();
    return checkboxGroup;
});

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

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

<f:variable name="items" value="{
    0: { value: 'dashboard', text: 'View Dashboard' },
    1: { value: 'reports', text: 'Access Reports' },
    2: { value: 'settings', text: 'Modify Settings' }
}" />

<ui:hydrationData name="checkbox-group" id="select-all-items" props="{items: items}" controlled="{true}" />

<div class="space-y-3">
    <ui:checkbox.root value="all" controlled="{true}" 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'}" controlled="{true}" rootId="select-all-group" style="margin-inline-start: 1rem;">
        <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>
</div>

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

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`	`array` 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	-

checkboxGroup.label

Labels the checkbox group. Renders a <span> element.

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>