In Magento 1, themes had a special file named local.xml. Through this file, a Magento 1 theme could directly modify the layout without needing to replace a specific layout update XML file.

Does Magento 2 have a similar mechanism? I know a Magento 2 theme can replace a layout handle XML file from a module -- what I want to know is does Magento 2 have a way for a theme to add layout rules that are specific to that theme.

If not, are there classes/methods provided that would allow a module developer to only add certain layout rules when a certain theme is added?


You have two options, you can either extend or overwrite the existing XML.


To extend an existing layout in a similar fashion to local.xml in Magento 1 you need to add an XML file in a location like this:


Where <layout1> and <layout2> are your layout handles, for example:


Official documentation can be found here - http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/layout-extend.html


Overwriting XML is done in the same way, it's just the file location that changes. You can overwrite the base module's XML or the parent theme's XML, the file location determines which is overwritten.

To overwrite the base module's XML place your XML file in:


To overwrite the parent theme's XML place your XML file in:


Official documentation can be seen here - http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/layout-override.html

  • Can u brief on the difference btwn Extending and Overwriting... like i have to get the Magento Catalogs toolbar.phtml (pagination) in my custom theme...which to follow – Sushivam Aug 18 '16 at 12:32
  • Can u give example for overwrite the base module's XML and To overwrite the parent theme's XML – Sushivam Aug 18 '16 at 12:42
  • 1
    The difference is extending will add your code on top of the base code, and overwriting will replace the base code. Generally speaking if you are making small changes then extending is usually best, if you are making a large customisation then overwriting may be best. But this won't always be the case. As for an example I will update the answer if I get time later today. – Ben Crook Aug 19 '16 at 8:59
  • ok Awaiting for an example: Like i want magento to use my custom toolbar.phmtl template, overriding Magentos Toolbar class – Sushivam Aug 19 '16 at 9:49
  • It might be better to ask the question as it's a bit different to this one. If you ask it in a new post and provide me the link I will give a detailed example for you – Ben Crook Aug 19 '16 at 12:42

Magento 2 has no concept of a local.xml file. However, when a theme includes a specific layout handle XML file from a specific module


Magento doesn't replace the original module's file, it simply merges the new layout handle XML file in the theme with the module's core file. Seems like a better system all around, as theme developers can no long accidentally remove important features.


I did not test this, but since you can add a web directory in the theme root for theme specific assets maybe it also might be possible to add theme specific layouts and / or templates there?

  • Didn't test it either, and the documentation seems to indicate that's not possible devdocs.magento.com/guides/v2.0/frontend-dev-guide/themes/… Hoping for a concrete answer before I spend a day doing all those experiments myself :) – Alan Storm Feb 5 '16 at 20:59
  • just thought, since layouts are not overridden anymore, but extended, there is no need anymore for a local.xml, is it? You should be able to extend any layout handle in any module, even if it is not defined in the original module. Maybe the Theme Module would then be the right place to do such things – David Verholen Feb 5 '16 at 21:09
  • Re: extended -- it sounds like you may have an answer to my second theming question :) magento.stackexchange.com/questions/100563/… – Alan Storm Feb 5 '16 at 21:10
  • indeed ;) just found it while searching for this problem – David Verholen Feb 5 '16 at 21:17

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.