Layout XML in Detail: Handles, Containers, References, Sorting

1. Handle Resolution: How Magento Resolves Layout XML Handles

In Magento's layout XML system, a handle is nothing more than an identifier under which any number of XML fragments from different modules and themes are collected and merged into a single layout tree. For every request, Magento assembles a stack of handles that always begins with a fixed baseline: the handle default is loaded on every single request, regardless of route or controller, and typically contains the base structure of root container, header, footer and the global blocks meant to appear on every page. Right after that, the view layer adds the so called full action name handle, composed of module name, controller and action in lowercase, for example catalog_product_view for the product detail page or cms_index_index for the homepage.

Beyond these two always active handles, Magento adds context dependent handles at runtime. The product detail page additionally adds type specific handles such as catalog_product_view_type_simple as well as id and sku based variants, so individual products can be targeted through layout XML without touching the generic handle. The customer session state adds customer_logged_in or customer_logged_out, which is especially relevant for full page cache variations. Custom handles of your own can additionally be pushed onto the stack at runtime via addHandle(), covered in more detail in section 7.

The order in which handles are pushed onto the stack directly determines the later merge order in layout XML: whatever is added later is also merged later and can override earlier definitions. Anyone unaware of this order will later wonder why a referenceBlock inside a custom handle appears to have no effect, even though the syntax is correct. This exact merge order is the topic of the next section.

2. Merge Mechanics: layout_update_type and Module Sorting

Internally, Magento distinguishes two kinds of layout files that can be described as layout_update_type: regular layout updates, meaning files such as catalog_product_view.xml that adjust blocks and containers within an existing page structure, and page layout files such as 1column.xml, 2columns-left.xml or empty.xml that define the fundamental root structure of a page. Which page layout file is used is defined through the layout attribute on the root node of the layout XML and is merged separately from the regular handle updates, before the actual handle files are layered on top.

Within the regular layout updates, a two stage sort determines the order in which files are merged. First the module order applies, computed via topological sorting from the sequence declaration in module.xml: modules that others depend on are processed first. Then the theme hierarchy applies, where the parent theme is merged before the child theme, so a child theme such as Mironsoft's own Hyva child theme can deliberately override definitions from hyva-themes/magento2-default-theme-csp. Within the same file, the plain order in the XML document itself decides last.

For identically named nodes in layout XML, the rule is: scalar attributes such as template or htmlClass are overwritten on every merge step, so the value merged last wins. Child elements, on the other hand, are merged additively rather than replaced, unless explicitly removed via remove or reordered via before/after. This understanding of the merge order is the foundation for everything that happens in referenceBlock, referenceContainer and move.

3. Container vs. Block: Which Element to Use in Layout XML

A <block> element in layout XML is always bound to a PHP class, typically a subclass of AbstractBlock, and usually renders a template. Blocks carry business logic, access ViewModels or repositories and produce actual HTML through _toHtml() or their template. A <container> element, by contrast, is pure structure with no PHP class of its own: it cannot hold logic, it only groups its child elements into a named unit that can be specifically referenced within layout XML.

The decisive practical difference lies in the rendering behavior. A container without the htmlTag attribute produces no wrapping markup at all when rendered, it simply returns the concatenated output of its children, exactly as the root container does in Hyva themes. Only with htmlTag="div" or htmlTag="header" does the container get an actual HTML element, complemented by htmlClass for the CSS class and htmlId for the id. For Tailwind driven Hyva layouts, this is the standard way to create semantic wrappers such as <aside> or <section> without having to write a dedicated block class for pure structure.

The rule of thumb for layout XML is therefore: use a container whenever only grouping or a semantic wrapper element is needed, use a block whenever actual presentation logic, a template or data access through a ViewModel is required. Anyone who instead creates an empty template block for every piece of structure produces unnecessary overhead and complicates later referenceContainer access, because a block then sits where a container would semantically be expected.

4. referenceBlock and referenceContainer: remove and display in Detail

<referenceBlock> and <referenceContainer> access an element already defined elsewhere in layout XML, in order to extend, reorder or remove it. The name must match the type exactly: applying a referenceBlock to an actual container produces no error but does not work reliably, because Magento internally uses different merge paths for the two element types. Anyone who wants to target a container must use referenceContainer instead.

Two attributes are regularly confused despite being fundamentally different: remove="true" completely removes the referenced element, including all its children, from the final layout tree. It is neither instantiated nor rendered, and the rendering overhead disappears entirely. The display="false" attribute, on the other hand, removes nothing. The block remains fully part of the layout tree, gets instantiated and stays programmatically reachable via getChildBlock(), only the automatic output through the parent's getChildHtml() is suppressed. This is relevant whenever a block should be output manually at a specific point in a template while never appearing in the automatic child output.

In practice this means: for permanent, final removal of a block for performance or security reasons, remove="true" is the right choice in layout XML. For a conditional or temporary hiding, where the block might be needed again later or referenced manually in a template, display="false" is the more appropriate and resource friendly variant compared to fully rebuilding the block elsewhere.

5. Sorting with before/after: Mechanics and Edge Cases

Within a container or block, the before and after attributes determine the relative position of a child element among its siblings in layout XML. before="targetname" places the element immediately before the named sibling, after="targetname" immediately after it. The special value - has a fixed meaning independent of any concrete target name: before="-" places the element in the very first position among all current siblings, after="-" in the very last position. This is especially useful for elements such as an alert banner that must always appear first, regardless of which other modules also add children to the same container.

An edge case that regularly leads to silent misbehavior in practice: if before or after references a sibling name that no longer exists at merge time, for instance because another module removed that block via remove="true", Magento throws no exception. Instead, the merge process silently falls back to simply appending at the end. This causes layout orderings that appear to change for no reason after a module update or a theme adjustment, without any error ever being logged.

Important for collaboration between multiple modules in the same layout XML container: before/after only ever works relative to elements already present in the tree during the same merge pass. If a referenced element is only defined in a file of the same handle that gets merged later, the sorting can behave unexpectedly in an intermediate state and only stabilize once the full merge pass has completed. For robust sorting it is therefore advisable to sort against stable anchor elements known across modules rather than against blocks from optional third party modules.

6. The move Element: Relocating Blocks Between Containers

While referenceBlock and referenceContainer leave an element at its original position in the tree and only extend or remove it there, <move> in layout XML is explicitly meant to relocate an already defined element into a different container. The syntax <move element="blockname" destination="containername" before="..." after="..."/> takes an element out of its previous parent and attaches it under the new destination container, optionally with an additional sort position via before or after.

The decisive advantage over duplicating an entire block definition at a new location: the original definition, including all arguments, child elements and adjustments already made by other modules, is fully preserved and merely gets hung at a different place in the tree. This is the standard approach in Hyva child themes for, say, relocating a newsletter teaser from the header to the footer without having to rewrite the original definition from the base theme. A second common use is moving entire containers together with all their already merged children, for example relocating a promotional banner from the sidebar to the area above the breadcrumbs.

<!-- Excerpt: content pages and campaign banner, container/block/referenceContainer -->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <!-- Container: pure structure, no PHP class, no template -->
        <container name="content.top.banner" as="content_top_banner" label="Content Top Banner" htmlTag="div" htmlClass="content-top-banner" before="-"/>

        <referenceContainer name="content">
            <!-- Block: bound to a PHP class, renders a template -->
            <block class="Mironsoft\LayoutTools\Block\CampaignBanner"
                   name="mironsoft.campaign.banner"
                   template="Mironsoft_LayoutTools::campaign/banner.phtml"
                   after="-">
                <arguments>
                    <argument name="view_model" xsi:type="object">Mironsoft\LayoutTools\ViewModel\CampaignBanner</argument>
                </arguments>
            </block>
        </referenceContainer>

        <!-- Hide without removing: block stays loaded, just not auto rendered -->
        <referenceBlock name="catalog.compare.sidebar" display="false"/>

        <!-- Remove entirely: block and children are dropped from the tree -->
        <referenceBlock name="right.reports.product.compared" remove="true"/>
    </body>
</page>

<!-- Sorting siblings with before/after inside a container -->
<referenceContainer name="header.container">
    <block class="Magento\Framework\View\Element\Template" name="header.alert.bar"
           template="Mironsoft_LayoutTools::header/alert-bar.phtml" before="-"/>
    <!-- before="-" places this block first among header.container children -->

    <block class="Magento\Framework\View\Element\Template" name="header.trust.badges"
           template="Mironsoft_LayoutTools::header/trust-badges.phtml" after="header.alert.bar"/>
    <!-- after="header.alert.bar" places this block directly behind the alert bar -->

    <block class="Magento\Framework\View\Element\Template" name="header.newsletter.teaser"
           template="Mironsoft_LayoutTools::header/newsletter-teaser.phtml" after="-"/>
    <!-- after="-" places this block last among all current siblings -->
</referenceContainer>

<!-- Edge case: referencing a sibling that no longer exists -->
<referenceContainer name="footer.container">
    <!-- If "footer.social.links" was removed by another module with remove="true",
         Magento silently falls back to appending this block at the end.
         No exception is thrown, the ordering just silently drifts. -->
    <block class="Magento\Framework\View\Element\Template" name="footer.legal.links"
           template="Mironsoft_LayoutTools::footer/legal-links.phtml" after="footer.social.links"/>
</referenceContainer>

<!-- Relocate an existing block into a different container, Hyva child theme example -->
<move element="header.newsletter.teaser" destination="footer.container" before="footer.legal.links"/>

<!-- Move a whole container together with its already merged children -->
<move element="content.top.banner" destination="page.top" after="breadcrumbs"/>

7. update handle and Custom Handles From the Controller

The element <update handle="other_handle"/> pulls an entire other handle, including all of its merged layout instructions, into the current context. This is the standard way in layout XML to share recurring structures such as a blog teaser bar or shared widget containers across multiple independent pages without maintaining the same XML definition more than once. Unlike move or referenceBlock, update handle does not create a reference to individual elements, it pulls the entire foreign handle in as an additional merge source for the current handle processing.

Static layout XML alone is not enough for dynamic, runtime dependent handles. A ViewModel no longer has access to layout loading by the time it is instantiated, it is already too late in the lifecycle. The right place is the controller action: before loadLayout() or before returning the Result\Page object, an additional handle can be pushed onto the stack via $resultPage->addHandle('custom_handle_name'), which is then merged like any other handle. This allows, for example, A/B variants, campaign pages or seasonal layout adjustments to be controlled cleanly through layout XML instead of conditional logic in the template.

<?php

declare(strict_types=1);

namespace Mironsoft\LayoutTools\Controller\Index;

use Magento\Framework\App\Action\HttpGetActionInterface;
use Magento\Framework\View\Result\Page;
use Magento\Framework\View\Result\PageFactory;
use Mironsoft\LayoutTools\Model\CampaignResolver;

/**
 * Controller action that conditionally adds a custom layout handle.
 * Constructor property promotion is used for all injected dependencies.
 */
final class Index implements HttpGetActionInterface
{
    /**
     * @param PageFactory $resultPageFactory Factory to create the page result.
     * @param CampaignResolver $campaignResolver Resolves the currently active campaign.
     */
    public function __construct(
        private readonly PageFactory $resultPageFactory,
        private readonly CampaignResolver $campaignResolver
    ) {
    }

    /**
     * Builds the page result and adds a custom layout handle when needed.
     *
     * @return Page
     */
    public function execute(): Page
    {
        $resultPage = $this->resultPageFactory->create();

        // Add a custom layout handle only when an active campaign matches.
        // This merges mironsoft_layouttools_campaign_active.xml on top of
        // the default and full_action_name handles.
        if ($this->campaignResolver->hasActiveCampaign()) {
            $resultPage->addHandle('mironsoft_layouttools_campaign_active');
        }

        return $resultPage;
    }
}

/**
 * ViewModel exposing campaign data to the template, no layout access here.
 */
namespace Mironsoft\LayoutTools\ViewModel;

use Magento\Framework\View\Element\Block\ArgumentInterface;
use Mironsoft\LayoutTools\Model\CampaignResolver;

final class CampaignBanner implements ArgumentInterface
{
    /**
     * @param CampaignResolver $campaignResolver Resolves the currently active campaign.
     */
    public function __construct(
        private readonly CampaignResolver $campaignResolver
    ) {
    }

    /**
     * Returns the label of the currently active campaign, or an empty string.
     *
     * @return string
     */
    public function getBannerText(): string
    {
        return $this->campaignResolver->getActiveCampaignLabel() ?? '';
    }
}

8. Generated Layout Cache: Invalidation in Hyva and Luma

The result of the entire handle merge process is stored in the layout cache type, so that not every request has to read and merge all layout XML files of every active module and theme again. The cache key is built from the concrete handle list of the request, the active theme, the store and the language, so different combinations of handle stack and theme each produce their own cache entries. This applies equally to Luma and Hyva, because the merge mechanism itself is part of the Magento core framework and works independently of the frontend theme in use.

For day to day development on Mironsoft's Hyva stack this means: changes to layout XML files do not become visible automatically while the layout cache is active. Unlike pure template or CSS changes, no Tailwind build and no static content deploy is enough here, what is needed specifically is bin/cache-clean layout or, during intensive development, disabling the cache type altogether. It is important to distinguish this from other cache layers: the full page cache caches finished HTML per page and customer segment, whereas the layout cache caches exclusively the merged XML structure before the actual rendering. A layout XML change that does not become visible is, in the vast majority of cases, caused by a still active layout cache entry, not by the full page cache.

9. Debugging Layout XML in Practice

The most important entry point for debugging layout XML is bin/magento dev:template-hints:enable. The command wraps every rendered template output in HTML comments containing the full template path, and it works regardless of whether a theme ships its own CSS for highlighting. In addition, dev:template-hints-blocks:enable also shows the name of the block in the layout tree, which often leads to the correct target for a referenceBlock faster than grepping through XML files.

For deeper analysis, a temporary debug block that outputs $block->getLayout()->getUpdate()->asString() or the corresponding XML structure directly is worthwhile, since it makes the fully merged state for the current handle stack visible instead of looking at individual source files in isolation. When block order is unclear, a targeted search for the block name via bin/cli grep -r "blockname" app/code app/design vendor/hyva-themes also helps to find every place where an element is touched via referenceBlock, move or update handle. After every layout XML change, the layout cache should consistently be cleared first before any further debugging steps are taken, otherwise a stale merge state gets mistaken for a bug.

<?php

declare(strict_types=1);

namespace Mironsoft\LayoutTools\Plugin;

use Magento\Framework\View\Element\AbstractBlock;
use Mironsoft\LayoutTools\Model\BlockVisibilityResolver;

/**
 * Plugin that conditionally suppresses block rendering at runtime,
 * complementing static remove/display attributes in layout XML.
 */
final class ConditionalBlockPlugin
{
    /**
     * @param BlockVisibilityResolver $visibilityResolver Resolves runtime visibility rules.
     */
    public function __construct(
        private readonly BlockVisibilityResolver $visibilityResolver
    ) {
    }

    /**
     * Suppresses HTML output for blocks that fail the visibility check.
     *
     * @param AbstractBlock $subject The intercepted block instance.
     * @param callable $proceed The original toHtml implementation.
     * @return string
     */
    public function aroundToHtml(AbstractBlock $subject, callable $proceed): string
    {
        if (!$this->visibilityResolver->isVisible($subject->getNameInLayout())) {
            return '';
        }

        return $proceed();
    }
}

/*
 * di.xml declaration that registers the plugin above.
 * A preference would not work here, since arbitrary block
 * classes across the whole application must be intercepted.
 *
 * File: app/code/Mironsoft/LayoutTools/etc/di.xml
 *
 * <?xml version="1.0"?>
 * <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
 *     <type name="Magento\Framework\View\Element\AbstractBlock">
 *         <plugin name="mironsoft_conditional_block"
 *                 type="Mironsoft\LayoutTools\Plugin\ConditionalBlockPlugin"
 *                 sortOrder="10"/>
 *     </type>
 * </config>
 */

The di.xml declaration in the comment block above shows how the interceptor is attached to AbstractBlock::toHtml(), which would not be possible statically through preferences, since arbitrary block classes can be affected.

The table summarizes which layout XML decisions are regularly made incorrectly in Mironsoft projects and which pattern leads instead to more robust, more maintainable Hyva themes. All five recommendations can be implemented purely through XML with no PHP code, except for the runtime dependent custom handle variant, which additionally requires a lean controller or plugin adjustment.

10. Summary

Magento 2.4.8's layout XML system follows a clear, but rarely fully documented, logic: handles are pushed onto a stack in a fixed order, starting with default, complemented by the full action name handle and optional context dependent or custom handles of your own. This order directly determines the merge order of XML fragments from all active modules and themes, with module sequence and theme hierarchy deciding the concrete priority. Container and block differ fundamentally in purpose and rendering behavior, referenceBlock and referenceContainer require exact type matching, and remove as well as display solve different problems.

Sorting via before/after, including the special value -, and the move element for relocations are the tools that keep complex Hyva layouts maintainable without duplication, as long as you know about the silent fallback when a reference target is missing. The layout cache delivers performance in production but demands disciplined cache clearing in development after every layout XML change. Once you understand handle resolution, merge mechanics and the sorting mechanics, you no longer debug layout XML by trial and error, but by deliberately tracing through the merge result.

11. FAQ: Layout XML in Magento 2