Extending a Magento widget layout within a theme

Extending a Magento widget layout within a theme

August 4, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Extending a Magento widget layout within a theme

Extending Magento Widget Layout within a Theme

Adding custom functionality to default Magento widgets is a common requirement for many projects. In this post, we’ll explore how to extend the Catalog Products List widget layout file found in vendor/magento/module-catalog/widget/etc/widget.xml.

The Challenge: Overriding the Default Widget XML File

The developer wants to add an additional template option (“Alternate Products Grid Template”) to the products_list widget. They have created a theme located at app/design/frontend/Vendor/theme, and placed their own version of the widget.xml file in app/design/frontend/Vendor/theme/Magento_CatalogWidget/widget.xml.

However, despite following best practices for theme configuration, the custom widget.xml file is not overriding the original one. This leads to the existing issue:

$ cat app/design/frontend/Vendor/theme/Magento_CatalogWidget/widget.xml

Understanding Magento Widget Structure

Before we dive into the solution, let’s understand how Magento widget layouts are structured.

The default widget.xml file in the magento-catalog-widget module defines a set of parameters for the products_list widget. These include options like “Title”, “Number of Products per Page”, and most importantly for our use case, the “Template” parameter:

<widget id="products_list"...>
    ...
    <parameter name="template" xsi:type="select" required="true" visible="true">
        ...
        <option name="default" value="product/widget/content/grid.phtml" selected="true">Products Grid Template</option>
        ...
    </parameter>
    ...
</widget>

The Solution: Correct Theme Configuration

The key to successfully overriding the default widget layout is proper theme configuration. It’s not enough to simply place the widget.xml file in your theme directory.

To extend the Magento widget layout, you must follow these steps:

  1. Create the Widget Layout XML File

Create a new XML file (let’s call it catalog_widget.xml) in your theme’s layout directory: app/design/frontend/Vendor/theme/Magento_CatalogWidget/layout/catalog_widget.xml.

  1. Define Your Extensions

Open this new file and define your extensions for the products_list widget:

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="catalog_widget_products_list">
            <block class="Magento\CatalogWidget\Block\Product\ProductsList"
                   template="Magento_CatalogWidget::product/widget/content/alternate-grid.phtml" />
        </referenceContainer>
    </body>
</page>
  1. Update the Theme’s etc/view.xml File

Open your theme’s etc/view.xml file and add a new XML node to include your custom layout:

<view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Theme:etc/view.xsd">
    ...
    <media>
        ...
    </media>
    <ui_component>
        ...
    </ui_component>
    <layout>
        <update handle="catalog_widget"/>
    </layout>
</view>
  1. Clear Cache

Finally, clear your Magento cache to ensure the changes take effect.

Conclusion

By following these steps and properly configuring your theme’s layout files, you should be able to successfully extend the widget.xml file for any built-in widget in Magento without touching the core framework.

This approach allows for a clean separation of concerns between your theme and the base system, ensuring that updates to the core do not overwrite your customizations. It also promotes better maintainability and easier theme upgrades or migrations.

Remember, always ensure you have proper version control in place when working with Magento themes. This helps prevent loss of work and facilitates easy collaboration if needed.

For more detailed information on Magento 2 theme development, check out our comprehensive guide at Laravel Company’s Magento 2 Theme Development Tutorial.

Catalog Extensions Themes Admin

Our network