Magento 2 – Overriding Template Files

20th July 2016

Magento 2 Overriding Template Files

You can override template files within Magento 2 thanks to its powerful theme inheritance feature. This means you can easily extend themes whilst minimising the maintenance efforts to do so.

For the purpose of this article, we will assume you have already created a basic theme directory structure. In this example, the custom theme’s parent is the blank theme provided by Magento 2 in its installation. So the homepage currently looks like the following:

The template files that are rendered on this page are currently coming from Magento’s blank theme. So how do we override template files for our own custom theme?

Taking a basic example, let’s assume we want to override the title.phtml file. If you have installed Magento via composer, this particular file resides in the following directory:

vendor/magento/module-theme/view/frontend/templates/html/title.phtml

You custom theme directory structure should reside in the app/design/frontend directory. e.g. app/design/frontend/[Your_Package]/[your-theme].

As title.phtml belongs in a module-theme/ directory, a Module_Theme directory will need to be created within your theme’s directory in order to override the file. The directory structure relative to the Magento 2 root directory should look like the following:

app/design/frontend/[Your_Package]/[your-theme]/Module_Theme/templates/html/title.phtml

Note how the first letters of module-theme get capitalised and the hyphen is replaced with an underscore.

Within title.phtml, you can make your own edits. For example, let’s add some additional text onto the end of the title.

<?php
$cssClass = $block->getCssClass() ? ' ' . $block->getCssClass() : '';
$title = '';
if (trim($block->getPageHeading())) {
    $title = '<span class="base" data-ui-id="page-title-wrapper" ' .  $block->getAddBaseAttribute() . '>'
        . $block->escapeHtml($block->getPageHeading()) . '</span>';
}
?>
<?php if ($title): ?>
    <div class="page-title-wrapper<?php /* @escapeNotVerified */ echo $cssClass; ?>">
        <h1 class="page-title"
            <?php if ($block->getId()): ?> id="<?php /* @escapeNotVerified */ echo $block->getId();?>" <?php endif; ?>
            <?php if ($block->getAddBaseAttributeAria()): ?>
                aria-labelledby="<?php /* @escapeNotVerified */ echo $block->getAddBaseAttributeAria(); ?>"
            <?php endif; ?>>
            <?php /* @escapeNotVerified */ echo $title . ' and more!'; ?>
        </h1>
        <?php echo $block->getChildHtml(); ?>
    </div>
<?php endif; ?>

If you refresh the page now, you should see the additional text.

This logic will also work for other template files. For example, to override the minicart.phtml file, first locate the file in the blank theme in the following directory.

vendor/magento/module-checkout/view/frontend/templates/cart/minicart.phtml

This means that you have to add it to the following path within your own theme:

app/design/frontend/[Your_Package]/[your-theme]/Module_Checkout/templates/cart/minicart.phtml

Don’t forget to enable template hinting for the frontend of the website! This will help you identify what templates from what theme are currently being rendered on the page. You can enable template hints by heading to Stores -> Configuration -> Advanced -> Developer within the admin panel.

Note: This article is based on Magento Community/Open Source version 2.1.