Home >Create New Layout, Extends, and Override Layout in Magento 2

Create New Layout, Extends, and Override Layout in Magento 2

Hi guys,

Today, we come back with a very new Magento tutorial: Layout customization. In this article, we will go together to find out how to create a new layout, extend and override layout.

1. Create a new layout 

In Magento 2, you can create a layout in the custom theme or in the custom module. Please follow these steps to create a new layout: 

Step 1: Create a page layout.

You need to create the layout-new.xml file: 

In the custom module: 


In the custom theme: 


<?xml version="1.0"?> <layout 
     <update handle="empty"/>     
     <referenceContainer name="page.wrapper">         
     <container name="header.container" as="header_container" label="Page Header Container" htmlTag="header" htmlClass="page-header" before="main.content"/>         
     <container name="page.top" as="page_top" label="After Page Header" after="header.container"/> 

Step 2: Add this new layout to the layouts.xml file.

Trong custom module:


Trong custom theme:


<?xml version="1.0" encoding="UTF-8"?> <page_layouts 
<layout id="layoutnew">         
     <label translate="true">New layout</label>    

Step 3: Flush Cache and check the result.

Go to Admin System Cache Management > Flush Magento Cache to flush cache or use this command: 

command: bin/magento cache:clean

The new page layout is displayed in the drop-down list of the layout option.

2. Extend layout 

Extend layout is used to modify default files without any replacement. 

2.1. Create the extend file in the theme

To extend the layout, you need to place the layout file in the following position:


For example: You want to modify this layout file: 


It is necessary to add a layout file with a similar name in the custom theme: 


You will place the page layout extend file in the following position: 


2.2. Extend layout in custom module

You can extend the layout of the module by creating the same layout file with the identical name in your custom module.

For example: You want to change the title of the “Create New Customer Account” page. 

Step1: Determine the layout file to be extended is the following file: 


Step 2: Create a layout extend file in custom module that has the same name as the above layout file.


Then change the title in the layout file to “Create New Customer Account custom module”.

<?xml version="1.0"?>
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        <title>Create New Customer Account custom module</title>

Step 3: Clear cache and check the result

2.3. Process the extend layout

Magento merges the layout files as below:

  • For each layout in the list:

+ Loads layout handle declaration and layout instructions.

+ The results will be added in the following format:

<layouts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <handle id="checkout_cart_index" label="Shopping Cart" type="page" parent="default">
        <!-- Layout instructions from checkout_cart_index.xml -->
    <handle id="checkout_onepage_index" label="One Page Checkout" type="page" parent="default">
        <!-- Layout instructions from checkout_onepage_index.xml -->
    <!-- ... -->

In which: id is defined by the name of the corresponding layout file and the handle attributes are determined at the root layout’s attributes

  • Replace the base URL placeholders in the result.

3. Override layout

Not all layout customizations can be implemented by extending the layout. If the number of customizations is large, you can use the override function for the layout file. It means that the new file you created in the theme will be used instead of the layout files in the parent theme of the base layout file.

To override, you must create a layout override file in your theme directory. Although you can override the base layout and theme layout with the same mechanism, there are some differences.

3.1. Override base layouts

To add a base layout override file (Overwrite the base layout provided by the module):

  • Create a layout file with the same name in the following location:
  • This file will overwrite the layout file:


For example: 

In case you desire to override the layout file: 


It is necessary to add a layout file with a similar name in the custom theme: 


3.2. Override theme layouts

Let’s follow these instructions to override the theme file:

  • Create a layout file with the same name in the following location:
  • This file will overwrite the layout file:


For example: You want to override this file: 


Then you have to create a file with the same name in your theme directory as below:


4. Impacts of overriding

When upgrading Magento, the original files of the modules can be updated. New blocks and containers may appear. If you have overwritten a file in which the block or container appeared in the update, the overridden modules cannot access them, leading to errors during running modules.

Hence, it is a must to add new changes to your files so that you can avoid that issue. Besides, please remember that you override some layout files in your theme and prepare to update Magento later.

Although the override mechanism provides flexibility for customization, it can be used to add unrelated changes logically. We strongly recommend that you should not make the following changes:

  • Do not change the name and aliases of the block
  • Do not change handling inheritance
< Previous Post
Next Post >
+ posts