Magento 2 Select Field: switcherConfig – Creating Dependent Fields Using Pure XML

What is switcherConfig?

switcherConfig is a powerful feature of Magento UI Components that allows you to define rules to control the behavior of one field based on the value of another field, without writing a single line of JavaScript. Concretely, it lets you show or hide fields, change their validation rules, enable or disable them, or trigger other actions based on user selections.

This is especially useful in Magento back-office (admin) forms, where dependencies between fields are very common.

XML structure of switcherConfig

Integration into the form

The switcherConfig is added inside the <settings> node of the triggering field, usually a select or radio field:

<field name="country">
  <argument name="data" xsi:type="array">
    <item name="config" xsi:type="array">
      <item name="formElement" xsi:type="string">select</item>
      <item name="component" xsi:type="string">Magento_Ui/js/form/element/select</item>
      <item name="options" xsi:type="array">
        <item name="0" xsi:type="array">
          <item name="value" xsi:type="string">FR</item>
          <item name="label" xsi:type="string" translate="true">France</item>
        </item>
        <item name="1" xsi:type="array">
          <item name="value" xsi:type="string">US</item>
          <item name="label" xsi:type="string" translate="true">United States</item>
        </item>
      </item>
    </item>
  </argument>
  <settings>
    <switcherConfig>
      <enabled>true</enabled>
      <rules>
        <!-- Rules go here -->
      </rules>
    </switcherConfig>
  </settings>
</field>

Rule anatomy

Each rule is declared as a numbered item inside the rules array. Important: always start indexing at 0, otherwise Magento may break:

<rules>
  <item name="0" xsi:type="array">
    <item name="value" xsi:type="string">FR</item>
    <item name="actions" xsi:type="array">
      <item name="0" xsi:type="array">
        <item name="target" xsi:type="string">namespace.namespace.fieldset.field_name</item>
        <item name="callback" xsi:type="string">show</item>
      </item>
      <item name="1" xsi:type="array">
        <item name="target" xsi:type="string">namespace.namespace.fieldset.other_field</item>
        <item name="callback" xsi:type="string">hide</item>
      </item>
    </item>
  </item>
  <item name="1" xsi:type="array">
    <item name="value" xsi:type="string">US</item>
    <item name="actions" xsi:type="array">
      <item name="0" xsi:type="array">
        <item name="target" xsi:type="string">namespace.namespace.fieldset.field_name</item>
        <item name="callback" xsi:type="string">hide</item>
      </item>
    </item>
  </item>
</rules>

Key elements

value: the value of the triggering field that activates the rule.
target: the full path of the target field, using the format
namespace.namespace.fieldset.field_name.
The namespace is duplicated (example: dumfr_customernew_form.dumfr_customernew_form).
callback: the action to execute on the target field (see next section).
params (optional): parameters passed to the callback.

Available callbacks

The most common callbacks are:

show: displays the target field.
hide: hides the target field.
enable: enables the target field.
disable: disables the target field.
setValidation: modifies the validation rules of the target field.

Example using setValidation:

<item name="0" xsi:type="array">
  <item name="target" xsi:type="string">dumfr_customernew_form.dumfr_customernew_form.company_fieldset.vat_id</item>
  <item name="callback" xsi:type="string">setValidation</item>
  <item name="params" xsi:type="array">
    <item name="0" xsi:type="string">required-entry</item>
    <item name="1" xsi:type="boolean">true</item>
  </item>
</item>

Here, the required-entry validation rule is added to the vat_id field when the rule is triggered.

Limitations and workarounds

Limitation 1: Exact value matching

By default, switcherConfig only triggers a rule when the value matches exactly. This becomes impractical for selects with hundreds of options. A workaround is to use a wildcard * by extending the switcher via a mixin:

define([
    'Magento_Ui/js/form/switcher'
], function (Switcher) {
    'use strict';

    return function (switcher) {
        return switcher.extend({
            applyRule: function (rule, value) {
                if (rule.value === '*') {
                    rule.actions.forEach(this.applyAction, this);
                    return;
                }

                return this._super(rule, value);
            }
        });
    };
});

Then declare this mixin in your requirejs-config.js:

config: {
    mixins: {
        'Magento_Ui/js/form/switcher': {
            'Dummy_Backend/js/form/switcher-mixin': true
        }
    }
}

You can now use:

<item name="value" xsi:type="string">*</item>
<item name="actions" xsi:type="array">
  <!-- This rule applies to ALL values -->
</item>

Limitation 2: Cannot directly change the `required` attribute

The setValidation callback does not allow you to directly change the required attribute of a field. To work around this, extend Magento_Ui/js/form/switcher with another mixin:

// Vendor/Module/view/adminhtml/web/js/form/switcher-mixin.js
define([
    'Magento_Ui/js/form/switcher',
    'uiRegistry'
], function (Switcher, registry) {
    'use strict';

    return function (switcher) {
        return switcher.extend({
            applyAction: function (action) {
                this._super(action);
 
                // adjust required according to rules
                registry.get(action.target, function (target) {
                    target.required(false);
                    target.validate();
                });
            }
        });
    };
});

Why doesn’t changing required-entry work? Quite simply because in Magento’s setValidation implementation you find:

if (changed) {
    this.required(!!rules['required-entry']);
    this.validate();
}

This code does not take the newly added rule into account.

Best practices

Test your target paths carefully: a mistake in namespace.namespace.fieldset.field_name will make the rule silently fail.
Always start indexing at 0: the first rule must be <item name="0" ...>, otherwise Magento may crash.
Use mixins to extend behavior: instead of modifying the core, create mixins to add custom callbacks or wildcard logic.
Combine multiple actions: a single rule can trigger multiple actions on different fields.

Summary

switcherConfig is a powerful XML-based tool for managing field dependencies without JavaScript. With a few well-placed mixins, you can overcome its native limitations and build dynamic, sophisticated Magento admin forms.