Magento's documentation (https://devdocs.magento.com/guides/v2.4/frontend-dev-guide/templates/template-walkthrough.html#template-customization-walkthrough) describes how to customise an existing template, by overriding it in your theme - copying the phtml from a core module into your theme then modify it.

It seems possible to add a new phtml template with a custom theme, not override an existing template. This can be achieved by creating the new phtml template in the Vendor/Theme/Magento_Theme/templates/my_new_template.phtml, where my_new_template.phtml was not an existing template in Magento_Theme. Then to get that new template onto the page by using a layout file, referencing that new template and giving it a standard block, like this

<referenceContainer name="some.reference">
    <block class="Magento\Framework\View\Element\Template" name="my.new.template" template="Magento_Theme::my_new_template.phtml" />

The key bit here is that my_new_template.phtml did not exist previously and is not being overridden. Its new.

Is this a Magento sanctioned method of adding a new template to a page from within a theme?

The [docs][1] I linked to at the start of this question do say

To add a new template in a theme:

Add a template in your theme directory according to the template storing convention.

Assign your template to a block in the corresponding layout file.

But there is no example and its unclear and I'm not sure I've interpreted this correctly.

Is this recommend by Magento?

[1]: https://devdocs.magento.com/guides/v2.4/frontend-dev-guide/templates/template-walkthrough.html#template-customization-walkthrough)

1 Answer 1


Yes, this is how you are supposed to add a new template.


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.