Bypassing Magento 2 layout update restrictions in Admin

Bypassing Magento 2 layout update restrictions in Admin

Magento’s layout system has been vastly improved in Magento 2 to be more accessible, more powerful and to be more streamlined. But, for some reason, only a very small subset of layout functions is made available for use in Magento 2 Admin (category layout XML updates, to be more precise). In this article, we’re going to show a very simple way of bypassing this pesky restriction.

Layout update restrictions in Magento 2 Admin

In the interest of keeping the example simple and straightforward, let’s say we want to remove the page title element from a specific category. In Magento 2 admin, in the category layout update XML field we add the following line.

<referenceBlock name="page.main.title" remove="true" />

And when we click save, we get the following error:

Please correct the XML data and try again. Element ‘referenceBlock’: This element is not expected. Expected is one of (referenceContainer, container, update, move ). Line: 1

It’s important to note that this XML would be valid if added using XML files in a theme. It seems that different standards apply for the layout update field in Magento 2 Admin and for the theme layout files.

So, only the following XML is allowed:

  • referenceContainer – we can reference existing containers
  • container – we can create new containers
  • update – we can include various layout handles
  • move – we can move existing blocks around

This info will help us bypass the restriction.

Bypassing the layout update restrictions

We can simply bypass this restriction by wrapping our referenceBlock code in referenceContainer code. But we need to find the container which contains our page title element. By doing a simple search in IDE, we find the following code snippet.

<referenceContainer name="">
<!-- ... -->
    <block class="Magento\Theme\Block\Html\Title" name="page.main.title" template="html/title.phtml"/>
            <container name="page.messages" htmlTag="div" htmlClass="page messages">
                <block class="Magento\Framework\View\Element\Template" name="ajax.message.placeholder" template="Magento_Theme::html/messages.phtml"/>
                <block class="Magento\Framework\View\Element\Messages" name="messages" as="messages" template="Magento_Theme::messages.phtml"/>
<!-- ... -->

We use the container and reference it in our Layout Update XML in Admin and wrap it around our initial code.

<referenceContainer name="">
    <referenceBlock name="page.main.title" remove="true" />

When we save this configuration, we do not get any errors on the category page in Admin and the page title block is removed on that specific category.


We hope to see these restrictions either removed from Magento 2 Admin XML layout update fields or better documentation that will explain the behavior in more detail. Magento 2 Admin would most certainly benefit of having unrestricted layout update features. Until then, we can hopefully use this bypass safely and hope that it’s upgrade-proof.

Related Inchoo Services

You made it all the way down here so you must have enjoyed this post! You may also like:

Magento 2 Custom CMS page layout Matej Djakovic
Matej Djakovic, | 7

Magento 2 Custom CMS page layout

Adding videos to product page in Magento2 Stanislav Mihic
Stanislav Mihic, | 4

Adding videos to product page in Magento2

Override Magento 2 Layout: Product page example Mladen Ristic
, | 6

Override Magento 2 Layout: Product page example


  1. Thanks for the great post. I would really love to hear your opinion on OVERUSE of static blocks with regards to optimizing a Magento site for search marketing.
    Additionally, we are always looking for Magento Developers that push the limits. We have a large portfolio of Magento clients. Would you be willing to have a chat about possibly working on some of our projects if it makes sense?
    You can find our site at: E-Commerce Business Consultants or please email me when you might have some time to discuss (if you have interest of course).

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <blockquote cite=""> <code> <del datetime=""> <em> <s> <strike> <strong>. You may use following syntax for source code: <pre><code>$current = "Inchoo";</code></pre>.

Tell us about your project

Drop us a line. We'd love to know more about your project.