The CHECKBOX_GROUP component provides multiple checkboxes from which users can select any combination of options.
🛝 Use the Dynamic Form Playground to see the Checkbox Group component in action and try out different configurations
| Property | Type | Required | Description |
|---|---|---|---|
type | 'CHECKBOX_GROUP' | Yes | Specifies the field type as CHECKBOX_GROUP. |
id | string | Yes | Unique identifier for the field. The field's value is stored in the form state under this key. |
renderName | string | No | Optional name added as data-render-name attribute to locate the rendered element in the DOM. |
label | string | Yes | Label text displayed above the checkbox group. Supports translation and string interpolation. |
value | string[] | No | The initially selected option values. Each entry must match the stringified value of one of the configured options. |
hint | string | No | Additional hint text displayed below the label. |
note | string | No | Informational note displayed when there are no errors. |
infoIcon | DfInfoIconConfig | No | Info icon with popover. Object with popoverText (string, required) and popoverDirection ('top', 'bottom', 'left', 'right'). |
validators | array | No | Validation rules for the field. Common type: REQUIRED (validates that at least one option is selected). Each validator has type and optional errorMessage. |
testId | string | No | Test identifier for automated testing. Set as data-testid attribute. |
acl | array | No | Access control rules for field visibility/editability. Each rule has state ('hidden', 'readonly', 'disabled', 'visible', 'editable') and optional condition (Filtrex expression). |
spacing | string | No | Margin spacing before next field: 'NONE' (0px), 'XS' (8px), 'S' (16px), 'M' (24px), 'L' (32px), 'XL' (40px), 'XXL' (48px). |
Note: This component does not support the columnSpan property, meaning that the component always spans the full width of the form (12 columns). Use layout.optionsColumnSpan to control the size of each option within the group instead.
| Property | Type | Required | Description |
|---|---|---|---|
options | DfOptions[] | string | Yes | The options for the checkbox group. Can be either: 1. A hardcoded array of objects for direct display. Each object must have a 'label' and 'value'.2. A string expression used by an option provider service to dynamically fetch options. See also DfOptions |
labelSizeSmall | boolean | No | Sets the checkbox label size to 'small'. The default size is 'large'. |
layout | HorizontalLayout | VerticalLayout | No | The layout configuration for the checkbox group. See also HorizontalLayout, VerticalLayout |
| Property | Type | Required | Description |
|---|---|---|---|
label | string | Yes | The label to display for the list |
value | string | number | boolean | Yes | The value of the option |
testId | string | No | The test id of the option used for automated tools, like cypress to find the componentand made independent of other config changes. If implemented, the value should be the following data-testid=VALUE_HEREwith the testid in lowercase. |
| Property | Type | Required | Description |
|---|---|---|---|
horizontal | boolean | Yes | Option to enable horizontal layout via configuration |
optionsColumnSpan | number | No | This size of each option. By default, each option takes 4 columns but you have an option to configure it to 3, 6 or 12 columns. For the best user experience, a 3-column span should be used only in expert journeys when fullWidthFormInExpert is set to true.For horizontal groups, a maximum of 3 options per row is allowed in retail journeys and expert journeys with half-width forms to maintain readability and spacing consistency. For expert journeys with full-width forms, horizontal groups can have up to 4 options per row. |
| Property | Type | Required | Description |
|---|---|---|---|
groupLabelLeftAlignInRetail | boolean | No | Option to left-align the group label in retail journeys. This option is applicable to vertical layouts only. The left-align label uses the same column span as the options. For long labels, it's recommended to set optionsColumnSpan to 6 or 12. |
horizontal | boolean | No | Option to enable horizontal layout via configuration |
optionsColumnSpan | number | No | This size of each option. By default, each option takes 4 columns but you have an option to configure it to 3, 6 or 12 columns. For the best user experience, a 3-column span should be used only in expert journeys when fullWidthFormInExpert is set to true.For horizontal groups, a maximum of 3 options per row is allowed in retail journeys and expert journeys with half-width forms to maintain readability and spacing consistency. For expert journeys with full-width forms, horizontal groups can have up to 4 options per row. |
{
"id": "coverageOptions",
"type": "CHECKBOX_GROUP",
"label": "Select coverage options",
"options": [
{ "label": "Liability", "value": "liability" },
{ "label": "Comprehensive", "value": "comprehensive" },
{ "label": "Collision", "value": "collision" }
]
}{
"id": "notifications",
"type": "CHECKBOX_GROUP",
"label": "Notification preferences",
"layout": { "horizontal": true },
"options": [
{ "label": "Email", "value": "email" },
{ "label": "SMS", "value": "sms" },
{ "label": "Push", "value": "push" }
]
}{
"id": "selectedAddOns",
"type": "CHECKBOX_GROUP",
"label": "Select add-ons",
"options": "$.availableAddOns"
}{
"id": "agreedPolicies",
"type": "CHECKBOX_GROUP",
"label": "You must agree to at least one policy",
"options": [
{ "label": "Privacy Policy", "value": "privacy" },
{ "label": "Terms of Service", "value": "terms" }
],
"validators": [{ "type": "REQUIRED", "errorMessage": "Please select at least one option" }]
}For complete API documentation, see DfCheckboxGroupConfig.
For Aquila component documentation and design guidelines, see Checkbox - Aquila Design System.