New UI Forms

Magnolia 6.4 UI is based on front-end technology (React) and a custom front-end design system built from the ground up for accessibility.

Magnolia’s New UI Forms and design system support equal access for everyone. They offer a modern design and help you build more readable, consistent, performant, and usable forms. Furthermore, it preserves your current features and improves their accessibility.

New UI Form example

Viewing New UI Forms

New UI Forms use the existing Magnolia form definitions but don’t support every field or every property. When a form definition is fully supported, the new form is displayed. Otherwise, the system will fall back to the standard Vaadin form. In this case, problems are shown in the Definitions app to indicate which features aren’t supported in the new UI. Set the new Problem type filter to UNSUPPORTED or IGNORED to see them.

Support for more fields is in development, but not all of the current behavior will be supported. To streamline the product, we’ll remove some rarely used features. See Current and planned support for more details.

Migrating to New UI Forms

You can always choose not to use the New UI Forms by adding the $type property to the existing form definition and setting it to vaadinForm:

...
    detail:
        form:
            $type: vaadinForm
            properties:
...

Quick checklist before upgrading:

Check form compatibility in the Definitions app (Problems subapp).
Fix or replace unsupported fields or properties.
Test forms in a development environment to confirm behavior and fallback handling.

To identify compatibility issues:

Open the Definitions app and use the Problems subapp.
Filter by Problem type:
- UNSUPPORTED — fields that cause the form to fall back to Vaadin.
- IGNORED — properties that the New UI Forms will ignore.

Behavior details:

Fallback: If any Vaadin field in a form lacks a New UI Forms equivalent, the whole form will render using Vaadin.
Partial support: New UI Forms will render when all fields are supported; otherwise Vaadin is used as a safe fallback.
Diagnostics: Use the Problems subapp to locate the specific field(s) or properties that require attention.

Migration guidance and notes:

Not all Vaadin fields and properties have New UI Forms equivalents. Expect to update some form definitions.
Update custom field implementations to provide New UI counterparts where possible, or replace usages with supported fields.
Test complex or decorated forms (subapps, decorated definitions). Decorations can introduce unsupported fields.

Example: Tours app - Detail subapp

This model definition, together with one decoration from the travel-demo-content-tags module (to add a TagsField), creates the Tours subapp you can see on the online demo.

model:
  nodeType: mgnl:content
  properties:
    - name: name
      required: true
    - name: description
      i18n: true
    - name: isFeatured
      type: Boolean
    - name: image
      required: true
      type: asset
    - name: tourTypes
      multiple: true
      type: reference:tourCategory
    - name: destination
      multiple: true
      type: reference:tourCategory
    - name: location
    - name: date
      type: Date
    - name: duration
      options:
        2-days:
          name: 2-days
          value: 2
        7-days:
          name: 7-days
          value: 7
        14-days:
          name: 14-days
          value: 14
        21-days:
          name: 21-days
          value: 21
      type: Long
    - name: author
    - name: body
      i18n: true
      type: richText

If you add a Slider field definition to the form definition of the detail subapp, the whole form falls back to Vaadin fields.

/tours/apps/tours.yaml

...
  detail:
    form:
      properties:
        name:
          i18n: true
        slider: (1)
          $type: sliderField
          label: Percentage
          defaultValue: 50
          stepSize: 5
          displayStepSize: 25
          valueFormat: PERCENTAGE

1	Unsupported `slider` field definition.

In 6.4 Switchable fields, setting removePreviouslySelected=false is not supported in New UI Forms.

If you rely on this property in your templates, see the migration information on page Migrating the removePreviouslySelected property.

Possible issues

Determine why a form is displayed as a Vaadin form

Are you seeing Vaadin forms instead of the New UI Forms?

Open the Definitions app, and switch to the Problems subapp.
Use the new Problem type filter and choose UNSUPPORTED.
You will now see the problems causing the form to display the Vaadin form.

See Current and planned support for details on which features we still plan to support in the future.

Check which properties are being ignored

Open the Definitions app, and switch to the Problems subapp. Use the new Problem type filter and choose IGNORED.

If it’s important for you that these properties are used in the form and not ignored, you can force a form to be displayed in Vaadin by setting the $type of the form to vaadinForm.

...
    detail:
        label: My App detail
        form:
            $type: vaadinForm
            properties:
...

See Current and planned support for a full list of which properties are ignored.

See all the problems of a form

In the Problems subapp, only the first problem of each definition is displayed. To see all the problems of a form, check the checkbox on the left to select the problem and use the Export problems action in the Action bar. A text file will be exported.

Use the new forms and Vaadin forms in parallel

Not every form type is supported as a New UI Form due to the many custom fields included in extensions or customer projects. There will be a transition period. You can continue to use Vaadin forms and upgrade them to the new forms as appropriate.

Current and planned support

This section outlines which standard Magnolia fields and related features are supported in the new UI.

Standard form fields supported

The standard fields are described in the Field definition section of the Magnolia documentation.

Supported fields	Fields not yet fully supported
checkBoxField	jsonComboBoxField
checkBoxGroupField	jsonLinkField
compositeField	sliderField
damLinkField	staticField
comboBoxField
dateField
jcrMultiField
jcrMultiLinkField (renders as jcrMultiField)
jcrMultiValueField
listSelectField
pageLinkField
radioButtonGroupField
richTextField
textField
tokenField (renders as comboBoxField)
twinColSelectField (renders as comboBoxField)
switchableField
passwordField
linkField

Supported fields

Fields not yet fully supported