I've been programming Magento 1 for many years but I'm just getting into Magento 2 and I am a little confused about the theme folder structure. From what I have found there's really no concept of theme-specific template files. Templates are inside modules now. To overwrite a parent theme's template, simply put your own template file in the same folder as the parent theme's file.

For example, let's say I have a theme called "Mytheme/Default" and I want to change the footer.phtml template for my theme. The default one lives in [site_root]\vendor\magento\module-theme\view\frontend\templates\html\footer.phtml. This tells me it's in the Magento Theme extension, so I need to put my override template in [site_root]/app/design/frontend/Mytheme/Default/Magento_Theme/templates/html/footer.phtml.

However, the part that isn't clear is where I'm supposed to put template files that are entirely custom but not related to any module at all. I have since learned that these should probably reside under the Magento_Theme extension, howerver, while playing around and trying things I discovered that I can create a templates subdirectory in my theme folder (outside of any Module folders) and it actually works. I can't find anything online about this so I'm wondering if it's a side effect of how Magento looks for template files or if this is actually a supported method for creating custom templates that aren't part of an extension.

I also read that if the template file you're trying to use lives in the same Module as the XML file providing the instructions you can avoid the Vendor_Module:: prefix on the template declaration in the XML. For instance, if I create a new block inside the body of a page and I instantiate this using a default.xml file inside my theme under the Magento_Theme module directory, and if I put my template somewhere in the same Magento_Theme module directory, I should be able to use template="path/to/template.phtml in my layout XML instead of the longer version, template="Magento_Theme::path/to/template.phtml". This, however, does not work in my experience and I always need the Magento_Theme:: directive.


If I put my custom template in the (perhaps unsupported) templates subdirectory inside my theme's root folder (i.e. ...app/design/frontend/Mytheme/Default/templates) I don't need any module prefix and it actually works.

Is this supported or is it just by happenstance that it's working?

2 Answers 2


The workflow you described (putting the templates inside app/design/frontend/Vendor/theme/templates) is not actually supported (actually, I've never tried myself, but if it is supported, is definetly not a good practice).

You should add your new templates inside the module folder (I ment, the folder that overrides a module in your theme) that you actually want to add/modify this view.

For example, if you want to add a new custom template to the footer, you should add it in the following path:


And, in your default.xml call it:

<block class="Magento\Framework\View\Element\Template" name="custom.template" template="Magento_Theme::footer/my-custom-template.phtml"/>

If the template is not related to any module, you should create a new module, and there you can add the template.

I hope this clarify you doubts.

  • Thanks for the answer, this is pretty much what I thought with one exception. I assumed that templates not associated with any existing block class could live under the Magento_Theme (as long as it doesn't need a custom block class). While this may work, is it not best practice? Should I have an extension for my custom theme that holds any templates and view-related logic?
    – Mageician
    Commented Jun 7, 2018 at 1:29

What you can do, that is kind of weird, is that you specify a random module template that doesn't exist and then you override that template in in your custom theme. You don't need to create a module. E.g. in your custom theme layout file (/app/design/frontend/Vendor/Theme/Magento_Theme/layout/default.xml) you can add:

<referenceContainer name="top.container">
    <block class="Magento\Framework\View\Element\Template" name="custom-nav-toggle" template="Magento_Theme::html/header/nav-toggle.phtml" />

And even though the module Magento_Theme doesn't have any such template, you can override it in your custom theme and it works, e.g. here is the contents of (app/design/frontend/Vendor/Theme/Magento_Theme/templates/html/header/nav-toggle.phtml):

<span data-action="toggle-nav" class="action nav-toggle"><span><?= $block->escapeHtml(__('Toggle Nav')) ?></span></span>

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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