---
title: "Variants"
manual: "Form"
version: "14.3"
permalink: "https://docs.typo3.org/permalink/typo3/cms-form:concepts-variants@14.3"
source: "I/Concepts/Variants/Index.rst"
rendered: "2026-09-19T11:59:02+00:00"
---

# Variants {#concepts-variants}

## Basics {#concepts-variants-basics}

A variant is an "alternative" form definition section that allows you to change
properties of form elements, validators, and finishers. Variants are activated
by conditions. This allows you to:

-   translate form element values depending on the frontend language
-   set and remove validators from one form element depending on the
    value of another form element
-   hide entire steps (form pages) depending on the value of a form
    element
-   set finisher options depending on the value of a form element
-   hide a form element in particular finishers and on the summary step

Form element variants can be defined statically in
form definitions or created programmatically through an API. The
variants defined in a form definition are applied to
a form based on their conditions at runtime. Programmatically defined variants
can be applied at any time.

Variant conditions can be evaluated programmatically
at any time. However, some conditions are only available at runtime,
for example, checking a form element value.

Custom conditions and operators can be easily added.

Only the form element properties listed in a variant are applied to the
form element, all other properties are retained. An exception to this
rule are finishers and validators. If finishers or validators are
**not** defined in a variant, the original finishers and validators
will be used. If at least one finisher or validator is defined in a
variant, the original finishers and validators are overwritten
by the finishers and validators in the variant.

Variants defined in a form definition are **all** processed and
applied in the order of their matching conditions. This means if
variant 1 sets the label of a form element to "X" and variant 2 sets
the label to "Y", then variant 2 is applied, i.e. the label will be "Y".

> [!NOTE]
> Currently it is **not** possible to define variants in
> the backend form editor.

## Rendering option `enabled` {#concepts-variants-enabled-property}

The rendering option `enabled` is available for all finishers and
form elements except the root form element and the first form
page. The option accepts a boolean value (`true` or `false`).

Setting a form element to `enabled: true` renders it in the
frontend and enables processing of its values, including property mapping
and validation. Setting `enabled: false` disables it in the frontend. All
form elements and finishers except the root form element and the first form page can be enabled
or disabled.

Setting a finisher to `enabled: true` executes it when
the form is submitted. Setting `enabled: false` skips the finisher.

By default, `enabled` is set to `true`.

See [examples](https://docs.typo3.org/permalink/typo3/cms-form:concepts-variants-examples-hide-form-elements@14.3)
below to learn more.

## Definition of variants {#concepts-variants-definition}

Variants are defined at the form element level in YAML. Here is an example of a text
form element variant:

```yaml
type: Text
identifier: text-1
label: Foo
variants:
  -
    identifier: variant-1
    condition: 'traverse(formValues, "checkbox-1") == 1'
    # If the condition matches, the label property of the form
    # element is set to the value 'Bar'
    label: Bar
```

The `identifier` must be unique at the form element level.

Each variant has a single `condition` which applies the variant if the
condition is satisfied. The
properties in the variant are applied to the form element. In the
example above the label of `text-1` is
changed to `Bar` if the checkbox `checkbox-1` is checked.

The following properties can be overwritten by `Form` (the topmost element)
variants:

-   `label`
-   `renderingOptions`
-   `finishers`
-   `rendererClassName`

The following properties can be overwritten by all other form element variants:

-   `enabled`
-   `label`
-   `defaultValue`
-   `properties`
-   `renderingOptions`
-   `validators`

> [!NOTE]
> Unset individual list items in select option variants by marking the values with
> `__UNSET`. See [example](https://docs.typo3.org/permalink/typo3/cms-form:concepts-variants-examples-remove-options@14.3) below.

## Conditions {#concepts-variants-conditions}

The form framework uses the Symfony component [expression language](https://symfony.com/doc/4.1/components/expression_language.html)
for conditions. An expression is a one-liner that returns a boolean value, for example,
`applicationContext matches "#Production/Local#"`. For further information see
the [Symfony docs](https://symfony.com/doc/4.1/components/expression_language/syntax.html).
The form framework extends the expression language with variables to access
form values and environment settings.

### `formRuntime` (object) {#concepts-variants-conditions-formruntime}

You can access every public method of `\TYPO3\CMS\Form\Domain\Runtime\FormRuntime`.
Learn more [here](https://docs.typo3.org/permalink/typo3/cms-form:apireference-frontendrendering-programmatically-apimethods-formruntime@14.3).

For example:

`formRuntime.getIdentifier() == "test"`.

### `renderable` (VariableRenderableInterface) {#concepts-variants-conditions-renderable}

`renderable` contains the instance of renderable that the condition
is applied to. This can be used e.g. to access the identifier of the
current renderable without having to duplicate it.

For example:

`traverse(formValues, renderable.getIdentifier()) == "special value"`.

### `formValues` (array) {#concepts-variants-conditions-formvalues}

`formValues` holds all the submitted form element values. Each
key in the array represents a form element identifier.

For example:

`traverse(formValues, "text-1") == "yes"`.

### `stepIdentifier` (string) {#concepts-variants-conditions-stepidentifier}

`stepIdentifier` is set to the `identifier` of the current
step.

For example:

`stepIdentifier == "page-1"`.

### `stepType` (string) {#concepts-variants-conditions-steptype}

`stepType` is set to the `type` of the current step.

For example:

`stepType == "SummaryPage"`.

### `finisherIdentifier` (string) {#concepts-variants-conditions-finisheridentifer}

`finisherIdentifier` is set to the `identifier` of the
current finisher or an empty string (if no finishers are executed).

For example:

`finisherIdentifier == "EmailToSender"`.

### `site` (object) {#concepts-variants-conditions-site}

You can access every public method in `\TYPO3\CMS\Core\Site\Entity\Site`.
The following are the most important ones:

-   getSettings() / The site settings array
-   getDefaultLanguage() / The default language object for the current site
-   getConfiguration() / The whole configuration of the current site
-   getIdentifier() / The identifier of the current site
-   getBase() / The base URL of the current site
-   getRootPageId() / The ID of the root page of the current site
-   getLanguages() / An array of available languages for the current site
-   getSets() / Configured site sets of a site (new in TYPO3 v13+)

For example:

`site("settings").get("myVariable") == "something"`.
`site("rootPageId") == "42"`.

More details on the `Site` object can be found in
[Using site configuration in conditions](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/UseSiteInConditions.html#sitehandling-inConditions).

### `siteLanguage` (object) {#concepts-variants-conditions-sitelanguage}

You can access every public method in `\TYPO3\CMS\Core\Site\Entity\SiteLanguage`.
The most important ones are:

-   getLanguageId() / The sys_language_uid.
-   getLocale() / The language locale, for example 'en_US.UTF-8'.
-   getTypo3Language() / The language key for XLF files, for example, 'de' or 'default'.
-   getTwoLetterIsoCode() / Returns the ISO-639-1 language ISO code, for example, 'de'.

For example:

`siteLanguage("locale").getName() == "de-DE"`.

### `applicationContext` (string) {#concepts-variants-conditions-applicationcontext}

`applicationContext` is set to the application context
(@see GeneralUtility::getApplicationContext()).

For example:

`applicationContext matches "#Production/Local#"`.

### `contentObject` (array) {#concepts-variants-conditions-contentobject}

`contentObject` contains the data of the current content object
or an empty array if no content object is available.

For example:

`contentObject["pid"] in [23, 42]`.

## Working with variants programmatically {#concepts-variants-programmatically}

Create a variant with conditions through the PHP API:

```
/** @var TYPO3\CMS\Form\Domain\Model\Renderable\RenderableVariantInterface $variant */
$variant = $formElement->createVariant([
    'identifier' => 'variant-1',
    'condition' => 'traverse(formValues, "checkbox-1") == 1',
    'label' => 'foo',
]);

```

Get all the variants of a form element:

```
/** @var TYPO3\CMS\Form\Domain\Model\Renderable\RenderableVariantInterface[] $variants */
$variants = $formElement->getVariants();

```

Apply a variant to a form element regardless of its conditions:

```
$formElement->applyVariant($variant);

```

## Examples {#concepts-variants-examples}

Here are some more complex examples to show you what is possible with the
form framework.

### Translation of form elements {#concepts-variants-examples-translation}

In this example, form, page and text elements have variants so that they are translated differently depending on
the frontend language (whether it is German or English).

```yaml
type: Form
prototypeName: standard
identifier: contact-form
label: Kontaktformular
renderingOptions:
  submitButtonLabel: Senden
variants:
  -
    identifier: language-variant-1
    condition: 'siteLanguage("locale").getName() == "en-US"'
    label: Contact form
    renderingOptions:
      submitButtonLabel: Submit
renderables:
  -
    type: Page
    identifier: page-1
    label: Kontaktdaten
    renderingOptions:
      previousButtonLabel: zurück
      nextButtonLabel: weiter
    variants:
      -
        identifier: language-variant-1
        condition: 'siteLanguage("locale").getName() == "en-US"'
        label: Contact data
        renderingOptions:
          previousButtonLabel: Previous step
          nextButtonLabel: Next step
    renderables:
      -
        type: Text
        identifier: text-1
        label: Vollständiger Name
        properties:
          fluidAdditionalAttributes:
            placeholder: Ihre vollständiger Name
        variants:
          -
            identifier: language-variant-1
            condition: 'siteLanguage("locale").getName() == "en-US"'
            label: Full name
            properties:
              fluidAdditionalAttributes:
                placeholder: Your full name
```

### Adding validators dynamically {#concepts-variants-examples-validation}

In this example, the `email-address` field has a variant that adds validators
if `checkbox-1` is checked.

```yaml
type: Form
prototypeName: standard
identifier: newsletter-subscription
label: Newsletter Subscription
renderables:
  -
    type: Page
    identifier: page-1
    label: General data
    renderables:
      -
        type: Text
        identifier: email-address
        label: Email address
        defaultValue:
        variants:
          -
            identifier: validation-1
            condition: 'traverse(formValues, "checkbox-1") == 1'
            properties:
              fluidAdditionalAttributes:
                required: required
            validators:
              -
                identifier: NotEmpty
              -
                identifier: EmailAddress
      -
        type: Checkbox
        identifier: checkbox-1
        label: Check this and email will be mandatory
```

### Hide form elements {#concepts-variants-examples-hide-form-elements}

In this example, the form element `email-address` has
been enabled explicitly but this can be left out as this is
the default state. The form element `text-3` has been disabled
to (temporarily) remove it from the form. The
field `text-1` has a variant that hides it in all finishers and on the summary step.
The `EmailToSender` finisher contains form values (`email-address`
and `name`). The `EmailToSender` finisher is only enabled if
`checkbox-1` has been checked by the user, otherwise it is skipped.

```yaml
type: Form
prototypeName: standard
identifier: hidden-field-form
label: Hidden field form
finishers:
  -
    identifier: EmailToReceiver
    options:
      subject: Yes, I am ready
      recipients:
        your.company@example.com: 'Your Company name'
      senderAddress: tritum@example.org
      senderName: tritum@example.org
  -
    identifier: EmailToSender
    options:
      subject: This is a copy of the form data
      recipients:
        {email-address}: '{name}'
      senderAddress: tritum@example.org
      senderName: tritum@example.org
      renderingOptions:
        enabled: '{checkbox-1}'
renderables:
  -
    type: Page
    identifier: page-1
    label: General data
    renderables:
      -
        type: Text
        identifier: text-1
        label: A field hidden on confirmation step and in all mails (finishers)
        variants:
          -
            identifier: hide-1
            renderingOptions:
              enabled: false
            condition: 'stepType == "SummaryPage" || finisherIdentifier in ["EmailToSender", "EmailToReceiver"]'
      -
        type: Text
        identifier: email-address
        label: Email address
        properties:
          fluidAdditionalAttributes:
            required: required
        renderingOptions:
          enabled: true
      -
        type: Text
        identifier: text-3
        label: A temporarily disabled field
        renderingOptions:
          enabled: false
      -
        type: Checkbox
        identifier: checkbox-1
        label: Check this and the sender gets an email
  -
    type: SummaryPage
    identifier: summarypage-1
    label: Confirmation
```

### Hide steps {#concepts-variants-examples-hide-steps}

In this example, the second step (`page-2`) has a variant that disables it
if `checkbox-1` is checked. `checkbox-1` has a variant which
disables it on the summary step.

```yaml
type: Form
prototypeName: standard
identifier: multi-step-form
label: Muli step form
renderables:
  -
    type: Page
    identifier: page-1
    label: First step
    renderables:
      -
        type: Text
        identifier: text-1
        label: A field
      -
        type: Checkbox
        identifier: checkbox-1
        label: Check this and the next step will be skipped
        variants:
          -
            identifier: variant-1
            condition: 'stepType == "SummaryPage"'
            renderingOptions:
              enabled: false
  -
    type: Page
    identifier: page-2
    label: Second step
    variants:
      -
        identifier: variant-2
        condition: 'traverse(formValues, "checkbox-1") == 1'
        renderingOptions:
          enabled: false
    renderables:
      -
        type: Text
        identifier: text-2
        label: Another field
  -
    type: SummaryPage
    identifier: summarypage-1
    label: Confirmation
```

### Set finisher values dynamically {#concepts-variants-examples-finisher}

In this example, the form has a variant so that the finisher has different values
depending on the application context.

```yaml
type: Form
prototypeName: standard
identifier: finisher-condition-example
label: Finishers under condition
finishers:
  -
    identifier: Confirmation
    options:
      message: I am NOT a local environment.
variants:
  -
    identifier: variant-1
    condition: 'applicationContext matches "#Production/Local#"'
    finishers:
      -
        identifier: Confirmation
        options:
          message: I am a local environment.
renderables:
  -
    type: Page
    identifier: page-1
    label: General data
    renderables:
      -
        type: Text
        identifier: text-1
        label: A field
```

### Remove select options {#concepts-variants-examples-remove-options}

In this example, a select form element has a variant which removes an option for
a specific locale.

```yaml
type: Form
prototypeName: standard
identifier: option-remove-example
label: Options removed under condition
renderables:
  -
    type: Page
    identifier: page-1
    label: Step
    renderables:
      -
        identifier: salutation
        type: SingleSelect
        label: Salutation
        properties:
          options:
            '': '---'
            mr: Mr.
            mrs: Mrs.
            miss: Miss
        defaultValue: ''
        variants:
          -
            identifier: salutation-variant
            condition: 'siteLanguage("locale").getName() == "zh-CN"'
            properties:
              options:
                miss: __UNSET
```

## Adding your own expression language providers {#concepts-variants-custom-language-providers}

You can extend the expression language with your own custom functions. For more
information see the official [docs](https://symfony.com/doc/5.4/components/expression_language/extending.html#using-expression-providers)
and the appropriate [TYPO3 implementation details](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SymfonyExpressionLanguage/Index.html#symfony-expression-language).

Register your own expression language provider class in
`Configuration/ExpressionLanguage.php` and create it, making sure it
implements `\Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface`.

**EXT:some_extension/Configuration/ExpressionLanguage.php**

```php
return [
    'form' => [
        Vendor\MyExtension\ExpressionLanguage\CustomExpressionLanguageProvider::class,
    ],
];
```

## Adding your own expression language variables {#concepts-variants-custom-language-variables}

You can extend the expression language with your own variables. These
variables can be used in conditions.

Register your own expression language provider class in
`Configuration/ExpressionLanguage.php` as above and
and create it as follows:

**EXT:some_extension/Classes/ExpressionLanguage/CustomExpressionLanguageProvider.php**

```php
class CustomExpressionLanguageProvider extends AbstractProvider
{
    public function __construct()
    {
        $this->expressionLanguageVariables = [
            'variableA' => 'valueB',
        ];
    }
}
```