Switchable field

info.magnolia.ui.field.ConfiguredSwitchableFieldDefinition renders a complex field that displays alternative forms depending on user choice. Use the field to switch, for example, between:

  • Plain text and rich text editors.

  • Unauthenticated and authenticated SMTP settings.

  • Same and different addresses for shipping and billing.

This switchable field definition is part of the Magnolia 6 UI framework. The fully qualified class name is info.magnolia.ui.field.ConfiguredSwitchableFieldDefinition.

If you work with the Magnolia 5 UI framework, see Switchable field for Magnolia 5 UI instead.

Example definition

  $type: switchableField
  label: Foo or bar options
    $type: radioButtonGroupField
    layout: horizontal
      $type: optionListDatasource
        - name: foo
          label: Foo
          value: foo
        - name: bar
          label: Bar
          value: bar
    $type: jcrChildNodeProvider
    - name: foo
          $type: textField
          label: Foo text
    - name: bar
          $type: richTextField
          label: Bar rich text

You can preview this example using the field-examples-module. See Field examples module for more information.

Field properties

Field-specific properties

Property Description



Node containing a select field and data source to switch between forms.

As $type, only comboBoxField and radioButtonGroupField are supported.

As datasource, only optionListDatasource can be used.

Options in radioButtonGroupField are positioned vertically by default. A horizontal layout can be configured using the common layout property of option group field.



List of forms to switch between. Forms define fields and similar components as well as their layout.

See Form definition for more information.


optional, default is true

A switchable field has different options, in which each option may have one or more fields. However, depending on the radio button selection, only one option is visible in the UI. An example switchable field is shown below.

Switchable field example

If the removePreviouslySelected property is set to true, only data for the selected (visible when viewed in the UI) option is saved.

Common complex field properties

Property Description



Name of the field definition item. Derived from the configured node name. Use alphanumeric characters without spaces.


required (unless $type is used)

Type of the field definition item. The value must be a fully qualified class name and a subtype of info.magnolia.ui.field.FieldDefinition. See Field types for possible values.


You can use this as a shortcut for class if the definition class is annotated with info.magnolia.ui.field.FieldType. The proper value is defined by the annotation.

Example class annotation
public class TextFieldDefinition extends ConfiguredFieldDefinition<String> {

See Field types for possible values.


optional, default is

  • JcrChildNodeProviderDefinition for JcrMultiFieldDefinition

  • CurrentItemProviderDefinition for StaticFieldViewDefinition

Node with a $type property that specifies the type of data binding for the subnodes in complex fields.

See Item providers for more information.

You can’t configure this property through YAML but it can be used in your Java code.



Help text displayed when the user clicks the help icon. The value can be literal or a key of a message bundle.


optional, default is false

Enables i18n authoring support, which allows editors to write foreign-language or regionally targeted content. A two-letter language identifier (en, de, fr, etc.) is displayed on controls where i18n is set to true.

When configuring CurrentItemProviderDefinition with i18n to true for a Switchable field, the i18n sub field must also be set to true.



Field label displayed to editors. The value can be literal or a key of a message bundle.

If you do not provide the property, Magnolia will fall back to a generated i18n key.

If you do not want to have any label, set the property to an empty string such as label: "" in YAML.



Additional style information for an editor property definition item applied to the element when the form is rendered. The value can be a CSS class or a list of CSS classes separated by white spaces.

The style name will be rendered as an HTML class name, which can be used in a CSS definition. The class name is added to the field by calling the Vaadin method addStyleName.

The referenced class can be defined in:


DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.