Layout XML Builder

How to Use the Magento 2 Layout XML Builder

The Layout XML Builder generates valid Magento 2 layout XML instructions for common block and container operations. Select a layout handle, choose your action type, fill in the relevant fields, and copy the ready-to-use XML directly into your module's view/frontend/layout/ directory.

Magento 2's layout XML system controls how every page is assembled from blocks and containers. Rather than modifying core files, all customizations — adding, removing, moving, and reconfiguring blocks — are expressed through XML instructions in your own module. Getting the XML structure exactly right is crucial: a missing attribute or incorrect nesting silently produces broken pages or PHP errors.

When to Use Each Action Type

• referenceBlock — Modify an existing block: change its template, add arguments, or set visibility. The most common operation for frontend customization.
• referenceContainer — Target an existing container to add child blocks or change its HTML tag and CSS classes.
• move — Reposition any block or container within the page structure without duplicating code. Essential for reordering sidebar widgets or product page sections.
• remove — Completely remove a block from the layout. Useful for hiding modules you have replaced or disabled.
• add CSS — Include a module-scoped CSS file via the head.css block, ensuring the asset loads on the selected handle only.
• add JS — Include a JavaScript file tied to a specific page handle, keeping page weight low on unrelated pages.

Layout Handle Scope

The default handle applies to every page in the store. All other handles — such as catalog_product_view or checkout_index_index — apply only on matching pages. Always use the most specific handle available to avoid unintended side-effects on other pages.

Common Mistakes

• Using an incorrect block name: block names are defined by the module that creates them and are case-sensitive. Use bin/magento dev:layout:dumps or inspect the merged layout XML in var/view_preprocessed to find exact names.
• Placing the layout file in the wrong area directory. Files for the frontend go in view/frontend/layout/; admin files go in view/adminhtml/layout/.
• Forgetting to flush the Magento cache after adding or editing layout files. Run bin/magento cache:clean layout full_page.