In this post, we will learn how to create a basic theme in Magento 2.

First of all, make sure you have a module ready. Click here to see how to create a module in Magento 2.

All themes in Magento 2 goes in:


Let us assume, our company name is Mycompany and our theme name is Basic. We need to create following directory structure for our theme:


— And —


Let us see the purpose of each folder:

Mycompany :-
The name of the company who is designing the theme

Basic :-
The name of the theme. We can have multiple named themes inside the company folder.

etc/view.xml :-
This file is used to specify product image dimensions, thumbnails etc.

Magento_Theme :-
This directory is used to override existing Magento’s theme files.

Magento_Theme/layout/default.xml :-
By default Magento2 assumes that your theme’s logo file should be: /web/media/logo.svg
If you want some other file for logo, then you must declare it in default.xml file.

This file is also used to override default theme’s settings.

media/preview.png :-
The preview of current theme.

web :-
This directory contains all the theme’s static data like images, styles, javascript, fonts etc.

registration.php :-
This file is required to register our theme to Magento2 system.

theme.xml :-
This is a compulsory file that defines our theme name, its parent and optionally theme’s preview image.

Creating theme files

Let us now create our files one by one.

theme.xml ( app/design/frontend/Mycompany/Basic/theme.xml )

<theme xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
   <title>Basic</title> <!-- your theme's name -->
   <parent>Magento/blank</parent> <!-- the parent theme -->
        <preview_image>media/preview.jpg</preview_image> <!-- theme's preview image -->

registration.php ( app/design/frontend/Mycompany/Basic/registration.php )


default.xml ( app/design/frontend/Mycompany/Basic/Magento_Theme/layout/default.xml )

<page xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <referenceBlock name="logo">
              <argument name="logo_file" xsi:type="string">images/my_logo.png</argument>
              <argument name="logo_img_width" xsi:type="number">200</argument>
              <argument name="logo_img_height" xsi:type="number">200</argument>

At this point, our theme is ready. Clear your cache and we will now select our new theme from admin.

Now, login to admin and move to following path:

Content -> Design -> Themes

You should see your theme listed.

Now go to:

Stores -> Configuration -> Design

Choose Main Website in front of Store View at top left. Now click Desgin -> Design Theme

Uncheck Use Default checkbox and pick your theme. Click Save Config, clear your cache and your new theme is ready. Check your home page.

Overriding Theme Templates

Sometimes we need to make modifications to existing templates. Instead of making changes directly to existing template files, we should override them in our own theme.

Let us assume that we want to update the category listing page ( list.phtml ). To do so, create following directory structure:


Here I assume that our current theme is Basic. Now copy the list.phtml file into product directory from the following location:


Now you can make any modifications you want to your overridden file.

Changing Theme Templates

To customize our Magento 2 stores, we need to do lot of customization.

Now, we will replace existing block templates with our own templates. Here is how to do:

Make sure, you have view/frontend/templates folder ready inside your module directory.

Create a new directory named header (you can give any name) inside view/frontend/templates folder. Next create a new file named top_links.phtml (you can give any name) inside header. Add following code to it:

<a href="home">Home</a> &nbsp;&nbsp;
<a href="contact">Contact Us</a>

Next, open the default.xml file from our theme: app/design/frontend/Mycompany/Basic/Magento_Theme/layout

Add following reference block to it:

<referenceBlock name="top.links">
        <argument name="template" xsi:type="string">Mymodule_Test::/header/top_links.phtml</argument>

Now, refresh cache and check your home page. You should see your own template for links is now displayed instead of default one.

Working with existing layouts

Now, we will see how we can modify & remove existing blocks/containers for a page. First, we would like to override the default.xml file provided with Magento.

  1. Create following folders in your current theme:
  2. Now copy the default.xml file from:

    to the folder


    You can have a look at blocks and containers defined in this file.

  3. Now, we will modify this layout from out own default.xml file created at the path:
  4. Let us say, we don’t want the top.links section. Under body section of this file, we can write:
    <referenceBlock name="top.links" remove="true"/>
  5. Let us say, we want to modify the whole footer according to our requirement. We can do:
    <referenceBlock name="footer_links" remove="true"/>
    <referenceBlock name="report.bugs" remove="true"/>
    <referenceBlock name="copyright" remove="true"/>
    <referenceContainer name="footer">
        <block class="Mymodule\Test\Block\Footer" name="main-footer" template="footer/main_footer.phtml"/>

    Create a block class named Footer (how to create blocks in Magento 2) in the file Footer.php inside the folder :


    Also, create the file main_footer.phtml: