Circle Toggle Group Component

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

1. Overview

The CIRCLE_TOGGLE_GROUP component provides a group of circular toggle buttons for selecting a single option from multiple choices. Each option can include an icon, SVG, or circle text for visual representation.

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

2. Key Features

Single selection from multiple circular toggle options
Visual customization with icons, SVGs, or circle text
Configurable column spans for layout control
Left-alignment option for expert journeys
Translation and string interpolation support for all text fields

3. Configuration Properties

Base Properties

Property	Type	Required	Description
`type`	`'CIRCLE_TOGGLE_GROUP'`	Yes	Specifies the field type as CIRCLE_TOGGLE_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 options. Supports translation and string interpolation.
`value`	`string`	No	The field's initial value. If set, the corresponding option will be pre-selected.
`validators`	`array`	No	Validation rules for the field. Common type: `REQUIRED`. The 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'` (48px), `'XXL'` (64px).

Note: This component does not support the hint or columnSpan properties at the component level (unlike other interactive components). Instead, hint is available on individual options (see DfCircleToggle properties below), and the component uses its own layout system via layout.optionsColumnSpan.

Component Specific Properties

Property	Type	Required	Description
`options`	`DfCircleToggle[]`	Yes	Configuration for all options to be displayed on a page. For the best user experience, retail journeys should not have more than 3 options. See also DfCircleToggle
`layout`	`object`	No	The layout of the field. See also Layout Properties

Options Properties (DfCircleToggle)

Property	Type	Required	Description
`label`	`string`	Yes	The label to be displayed as bold text under the option. It's translatable by default and supports string interpolation.
`value`	`string`	Yes	Value of the option to be used as a form value when the option is selected.
`circleText`	`string`	No	Text displayed in the option. It's translatable by default and supports string interpolation.
`hint`	`string`	No	The hint text to be displayed under the label. It's translatable by default and supports string interpolation.
`icon`	`string`	No	Name of the icon representing the option. Available icon names can be found in the NDBX documentation: https://ngx-brand-kit.frameworks.allianz.io/documentation/icon/overview.
`svg`	`string`	No	Path to an SVG file to be used as the icon for this option.
`svgChecked`	`string`	No	Path to an SVG file to be used as the icon when this option is selected.

Layout Properties

Property	Type	Required	Description
`optionsColumnSpan`	`number`	No	This size of each option. By default, each option takes 4 columns but you have an option to configure it to 2 or 3 columns. For the best user experience, a 2-column span should be used only in expert journeys when `fullWidthFormInExpert` is set to `true`.
`optionsLeftAlignInExpert`	`boolean`	No	Controls alignment for the circle toggle options. Set to `true` to left-align the options. Defaults to center alignment. Ignored in retail journeys.

4. Configuration Examples

Single Selection with Icons

{
  "id": "insuranceType",
  "type": "CIRCLE_TOGGLE_GROUP",
  "label": "Select Insurance Type",
  "options": [
    {
      "label": "Car Insurance",
      "value": "car",
      "icon": "product-car-front",
      "hint": "Comprehensive coverage"
    },
    {
      "label": "Home Insurance",
      "value": "home",
      "icon": "product-house",
      "hint": "Property protection"
    },
    {
      "label": "Travel Insurance",
      "value": "travel",
      "icon": "product-travel",
      "hint": "Worldwide coverage"
    }
  ],
  "validators": [
    {
      "type": "REQUIRED",
      "errorMessage": "Please select an insurance type"
    }
  ]
}

With Custom SVG Icons

{
  "id": "coverageAmount",
  "type": "CIRCLE_TOGGLE_GROUP",
  "label": "Select Coverage Amount",
  "options": [
    {
      "label": "€100k",
      "value": "100000",
      "svg": "assets/images/coverage-basic.svg",
      "svgChecked": "assets/images/coverage-basic-active.svg"
    },
    {
      "label": "€250k",
      "value": "250000",
      "svg": "assets/images/coverage-standard.svg",
      "svgChecked": "assets/images/coverage-standard-active.svg"
    }
  ]
}

With Custom Layout

{
  "id": "packageSelection",
  "type": "CIRCLE_TOGGLE_GROUP",
  "label": "Choose Your Package",
  "layout": {
    "optionsColumnSpan": 4,
    "optionsLeftAlignInExpert": true
  },
  "options": [
    {
      "label": "Basic",
      "value": "basic",
      "circleText": "B"
    },
    {
      "label": "Standard",
      "value": "standard",
      "circleText": "S"
    },
    {
      "label": "Premium",
      "value": "premium",
      "circleText": "P"
    }
  ]
}

5. API Reference

For complete API documentation, see DfCircleToggleGroupConfig.

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