# Checkbox Group

**A group of checkboxes for selecting multiple values.**

**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/CheckboxGroup)

**CheckboxGroup.html**

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

**CheckboxGroup.ts**

```ts
import { mountAll } from 'fluid-primitives';
import { CheckboxGroup } from 'fluid-primitives/checkbox-group';

mountAll('checkboxGroup', ({ 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

```bash
typo3 ui:add checkbox-group
```

Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives.com/tree/main/packages/docs/Resources/Private/Registry/CheckboxGroup) into your project.

Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).

## Examples

### Default Checked

Pre-select multiple options using an array of values.

**CheckboxGroup.html**

```html
<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.

**CheckboxGroup.html**

```html
<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.

**CheckboxGroup.html**

```html
<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.

**CheckboxGroup.html**

```html
<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.

**CheckboxGroup.html**

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

### checkboxGroup.root

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

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `defaultValue` | `array` | No | `-` | 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. |
| `name` | `string` | No | `-` | The name of the input fields in the checkbox group. Useful for form submission. Inherited from a surrounding field when available. |
| `form` | `string` | No | `-` | The form id the checkbox group belongs to. |
| `disabled` | `boolean` | No | `-` | If true, the checkbox group is disabled. Inherited from a surrounding field when available. |
| `readOnly` | `boolean` | No | `-` | If true, the checkbox group is read-only. Inherited from a surrounding field when available. |
| `required` | `boolean` | No | `-` | If true, the checkbox group is required. Inherited from a surrounding field when available. |
| `invalid` | `boolean` | No | `-` | If true, the checkbox group is invalid. Inherited from a surrounding field when available. |
| `maxSelectedValues` | `integer` | No | `-` | The maximum number of selected values. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. |
| `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. |
| `controlled` | `boolean` | No | `false` | If true, the component is meant to be initialized manually inside another component |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

### checkboxGroup.label

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

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

## Anatomy

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