Checkbox Component

1. Overview
2. Key Features
3. Configuration Properties
- Base Properties
- Component Specific Properties
4. Configuration Examples
5. API Reference

1. Overview

The CHECKBOX component provides a single checkbox for boolean selections, such as accepting terms and conditions or toggling preferences.

🛝 Use the Dynamic Form Playground to see the Checkbox component in action and try out different configurations

2. Key Features

Single boolean selection with configurable label
Support for small or large label sizes
Translation and string interpolation support
Validation support for required checkbox

3. Configuration Properties

Base Properties

Property	Type	Required	Description
`type`	`'CHECKBOX'`	Yes	Specifies the field type as CHECKBOX.
`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 next to the checkbox. Supports translation and string interpolation.
`value`	`boolean`	No	The field's initial value. If set, the checkbox will be pre-checked/unchecked based on this value.
`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_TRUE` (validates that checkbox is checked). 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).
`columnSpan`	`number`	No	Number of columns to span (1-12) in CUSTOM_COLUMN layout. Default: 12 (full width).
`spacing`	`string`	No	Margin spacing before next field: `'NONE'` (0px), `'XS'` (8px), `'S'` (16px), `'M'` (24px), `'L'` (32px), `'XL'` (48px), `'XXL'` (64px).

Component Specific Properties

Property	Type	Required	Description
`labelSizeSmall`	`boolean`	No	Sets the checkbox label size to 'small'. The default size is 'large'.

4. Configuration Examples

Important: For checkboxes that must be checked (like terms acceptance), use REQUIRED_TRUE validator to ensure the checkbox is actually checked.

Single Checkbox

{
  "id": "termsAccepted",
  "type": "CHECKBOX",
  "label": "I accept the terms and conditions",
  "validators": [
    {
      "type": "REQUIRED_TRUE",
      "errorMessage": "You must accept the terms and conditions"
    }
  ]
}

Checkbox with Small Label

{
  "id": "newsletter",
  "type": "CHECKBOX",
  "label": "Subscribe to newsletter",
  "labelSizeSmall": true
}

Checkbox with Hint

{
  "id": "marketingConsent",
  "type": "CHECKBOX",
  "label": "I agree to receive marketing communications",
  "hint": "You can unsubscribe at any time"
}

Checkbox with Note

{
  "id": "dataProcessing",
  "type": "CHECKBOX",
  "label": "I consent to data processing",
  "note": "This information is used solely for account verification purposes"
}

Checkbox with Info Icon

{
  "id": "advancedMode",
  "type": "CHECKBOX",
  "label": "Enable advanced mode",
  "infoIcon": {
    "popoverText": "Advanced mode enables additional features"
  }
}

Checkbox with Access Control

{
  "id": "adminOption",
  "type": "CHECKBOX",
  "label": "Admin only option",
  "acl": [
    {
      "state": "disabled"
    }
  ]
}

5. API Reference

For complete API documentation, see DfCheckboxConfig.

For Aquila component documentation and design guidelines, see Checkbox - Aquila Design System.