In Magento 2 (Adobe Commerce), the system.xml file is the backbone of the administrative configuration interface. One of its most powerful features is the <depends> tag, which allows you to show or hide fields based on the values of other fields.

While setting up a dependency within the same group is straightforward, you will often encounter scenarios where a field in one group (e.g., "Connection Settings") needs to react to a toggle located in a completely different group (e.g., "General Settings"). If you use the standard field ID in these cases, the dependency will fail because Magento's configuration engine defaults to looking within the local group scope.

In this guide, you will learn how to correctly reference fields across different groups and sections to create a seamless user experience in your module's configuration.

The Anatomy of Cross-Group Dependencies

When two fields reside in the same group, you can simply use the field's ID. However, when the fields are separated by groups or sections, you must provide the full path to the source field. The syntax follows a specific hierarchy: section_id/group_id/field_id.

Implementation Example

Suppose you have a "General Configuration" group with an enable toggle and a "Connection Configuration" group with a certificate check field. To make the certificate check depend on the enable toggle, you would structure your XML as follows:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <section id="my_custom_section" translate="label" type="text" sortOrder="200" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>My Extension</label>
            <tab>service_tab</tab>
            <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>General Configuration</label>
                <field id="enable_module" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Enable</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
            </group>
            <group id="connection" translate="label" type="text" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>Connection Configuration</label>
                <field id="disable_certificate_check" translate="label" type="select" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Check Certificate</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                    <!-- Referencing field in a different group -->
                    <depends>
                        <field id="my_custom_section/general/enable_module">1</field>
                    </depends>
                </field>
            </group>
        </section>
    </system>
</config>

By using <field id="section_id/group_id/field_id">, you tell Magento exactly where to look in the configuration tree to find the value required for the logic check.

Using Wildcards for Internal Section Dependencies

If your fields are in different groups but remain within the same section, you can use a shorthand wildcard syntax. This is particularly useful if you anticipate the section ID might change or if you want to keep the code more concise.

Instead of the full path, you can use:

<depends>
    <field id="*/*/active">1</field>
</depends>

In this context, the asterisks act as placeholders for the current section and the current group. However, when jumping between groups, the second asterisk must be replaced if the field is in another group. Generally, for cross-group dependencies, providing the full path is the most reliable method to avoid ambiguity.

Making Entire Groups Dependent

Magento also allows you to hide an entire group of settings based on a single field value. This is a great way to reduce "admin clutter." To achieve this, place the <depends> node directly inside the <group> tag rather than an individual <field> tag.

<group id="advanced_settings" translate="label" type="text" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Advanced Settings</label>
    <depends>
        <field id="my_custom_section/general/enable_module">1</field>
    </depends>
    <field id="secret_key" translate="label" type="text" sortOrder="10" showInDefault="1">
        <label>Secret Key</label>
    </field>
</group>

Handling Complex Logic with jQuery (Legacy & Edge Cases)

In some older versions (like Magento 2.1.x) or when you need logic that the standard XML schema doesn't support (like "show if field A is 1 AND field B is 2"), you might need to resort to a JavaScript-based approach. While not recommended for modern Adobe Commerce versions due to maintainability, it is a valid community workaround for complex UI toggling.

You can inject a script via the <comment> tag in your system.xml:

<comment><![CDATA[
<script type="text/javascript">
    require(['jquery'], function(jQuery){
        function toggleDependantGroups(hide) {
            if (hide) {
                jQuery('#section_id_group_id').hide();
            } else {
                jQuery('#section_id_group_id').show();
            }
        }

        jQuery('#my_custom_section_general_enable_module').change(function() {
            toggleDependantGroups(jQuery(this).val() == '0');
        }).change();
    });
</script>]]>
</comment>

Note: Always try to achieve your goals with the native XML <depends> tag first, as it handles scope (Default vs Website vs Store) much more gracefully than custom JS.

Common Mistakes to Avoid

  1. Incorrect Pathing: The most common error is forgetting the section ID in the path. Even if you are in the same section, group_id/field_id is often insufficient; use the full section/group/field string.
  2. Cache Issues: system.xml changes are cached. Always run bin/magento cache:clean config after modifying your dependencies.
  3. Scope Mismatches: If the source field is set to showInDefault="1" but the dependent field is showInStore="1", ensure the values exist at the level the user is currently viewing.
  4. Source Models: Ensure the source field uses a consistent source model (like Yesno). If the value in the database is 1 but your dependency is looking for true, it will fail.

Frequently Asked Questions

Can a field depend on multiple other fields?

Yes, you can include multiple <field> tags inside a single <depends> block. By default, Magento treats these as an "AND" operation—all conditions must be met for the field to appear.

Does this work across different modules?

Yes. As long as the section, group, and field IDs exist in the merged Magento configuration, you can create a dependency on a field defined in a completely different module (e.g., depending on a core catalog or sales setting).

Why is my dependency not working in the Store view scope?

Check the showInDefault, showInWebsite, and showInStore attributes for both fields. If the source field is hidden in the current scope, the dependency logic may not trigger as expected.

Wrapping Up

Mastering dependencies in system.xml is essential for building professional, user-friendly Magento extensions. By using the section/group/field pathing convention, you can create complex configuration screens that guide the user and prevent invalid settings from being entered.

Always prioritize the native XML approach for better compatibility with Adobe Commerce updates and only use JavaScript workarounds for logic that falls outside the standard capabilities of the Magento_Config module.