Radio Component

1. Overview
2. Key Features
3. Configuration Properties
4. Configuration Examples
5. API Reference

1. Overview

The RADIO component provides a group of radio buttons where users can select exactly one option from multiple choices.

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

2. Key Features

Single selection from multiple options
Horizontal or vertical layout options
Static or dynamic option fetching
Configurable column spans for layout control
Left-aligned group label option for retail journeys
Translation and string interpolation support

3. Configuration Properties

Base Properties

Property	Type	Required	Description
`type`	`'RADIO'`	Yes	Specifies the field type as RADIO.
`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 options. Supports translation and string interpolation.
`value`	`string \| number`	No	The field's initial value. If set, the corresponding option will be pre-selected.
`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`. 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).

Note: This component does not support the hint property, unlike most other interactive components.

Component Specific Properties

Property	Type	Required	Description
`options`	`DfOptions[] \| string`	Yes	The `options` property can take one of two forms: 1. A hardcoded array of objects for direct display in a radio group. Each object must have a `label` to display and a corresponding `value`. 2. A string that represents an expression. This expression is used by an option provider service to dynamically fetch the radio options. See also DfOptions
`layout`	`HorizontalLayout \| VerticalLayout`	No	The layout of the field. See also HorizontalLayout, VerticalLayout

Options Properties (DfOptions)

Property	Type	Required	Description
`label`	`string`	Yes	The label to display for the list
`value`	`string \| number`	Yes	The value of the option
`testId`	`string`	No	The test id of the option used for automated tools, like `cypress` to find the component and made independent of other config changes. If implemented, the value should be the following `data-testid=VALUE_HERE` with the `testid` in lowercase.

Layout Configuration (HorizontalLayout)

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.

Layout Configuration (VerticalLayout)

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.

4. Configuration Examples

Basic Radio Button Group

{
  "id": "insuranceType",
  "type": "RADIO",
  "label": "Select Insurance Type",
  "options": [
    {
      "label": "Life Insurance",
      "value": "life"
    },
    {
      "label": "Health Insurance",
      "value": "health"
    },
    {
      "label": "Vehicle Insurance",
      "value": "vehicle"
    }
  ],
  "validators": [
    {
      "type": "REQUIRED"
    }
  ]
}

Horizontal Radio Buttons

{
  "id": "gender",
  "type": "RADIO",
  "label": "Gender",
  "layout": {
    "horizontal": true
  },
  "options": [
    {
      "label": "Male",
      "value": "male"
    },
    {
      "label": "Female",
      "value": "female"
    },
    {
      "label": "Other",
      "value": "other"
    }
  ]
}

Radio with Custom Column Span

{
  "id": "hasPreExistingCondition",
  "type": "RADIO",
  "label": "Do you have any pre-existing medical conditions?",
  "layout": {
    "optionsColumnSpan": 6
  },
  "options": [
    {
      "label": "Yes",
      "value": "yes"
    },
    {
      "label": "No",
      "value": "no"
    }
  ],
  "validators": [
    {
      "type": "REQUIRED",
      "errorMessage": "Please select an option"
    }
  ]
}

Dynamic Radio with Expression

{
  "id": "insurancePlan",
  "type": "RADIO",
  "label": "Select Insurance Plan",
  "options": "$.availableInsurancePlans",
  "validators": [
    {
      "type": "REQUIRED",
      "errorMessage": "Please select an insurance plan"
    }
  ]
}

5. API Reference

For complete API documentation, see DfRadioConfig.

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