A Beginner's Guide to Magento 2 Theme Development

Magento eCommerce 2 Theme Development

After waiting for a while, Magento 2.0 was finally released last year. But, still a lot of people haven't moved to the new Magento version release yet. This article would drive you through the basic steps to create a new theme for Magento eCommerce store.


  • Coding experience with any version of Magento
  • Local installation of Magento 2.0 on your machine
  • Basic knowledge on Magento theme structure and modification techniques

: You should never modify default Magento templates for easy upgradation and maintenance purpose. Instead, consider creating a new custom Magento theme that overrides default functionality.

Get Started With Magento 2 Theme Development

Here, you'll find several steps that you need to follow to create and manage a Magento theme.

Step 1 – Create Your Theme Directory Structure

Just like Magento 1.x version, the themes in the new Magento 2 version release also needs to be stored inside the frontend directory. For this purpose, navigate to <your Magento install dir>/app/design/frontend.

Next, you'll have to create a new directory that will be named after your store's vendor name that will look something like this: /app/design/frontend/<Vendor>

And then, underneath your vendor directory, you need to create a directory named after your theme. This is how your directory structure will look like:

Magento Ecommerce Theme Scaffolding
Magento Ecommerce Theme Scaffolding

Step 2 – Theme Declaration

Once you've finished creating the directory structure, next you'll have to declare your theme. This is important as it will inform Magento about the existence of your newly created directory, which you can later set to be the active theme within your store's admin panel. To do so, inside your theme folder create theme.xml file.

Note: The theme.xml file must contain the new theme and parent theme names (in the case your theme inherits from an existing theme).

Within the theme.xml file, you can either use the code present in the Luma or Blank Magento themes folder. Or else, use the following code:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Enter Your Theme Name Here</title>

In the above code snippet, you just need to enter theme name within the tags. Also, you can declare the name of the parent theme inside tags for fallback purposes.

Step 3 – Declare a Theme Image (Optional)

When declaring new Magento 2.0 theme, you only need the above code snippet. However, you can consider declaring the theme preview image within the code as you deem perfect.

The preview image is a thumbnail image that is displayed in the admin panel on your theme page. Just as the name suggest, the image provides a preview of how your theme would look like.

To include theme preview image, add below piece of code between the <theme> tags, and right under the <parent> theme declaration:


Next, change your thumbnail image name in your file name. And then, put your image in the below mentioned location:


Step 4 – Add a registration.php File to Theme's Root

In this part, you are required to declare your theme within your system. This can be achieved by adding a registration.php file to the root of your theme:

~/app/design/frontend/<Vendor_Name>/<ThemeName> /registration.php

Also, you must copy and paste the below code in your registration.php file:

* Copyright © 2016 Magento. All rights reserved.
* See COPYING.txt for license details.


Step 5 – Turn Your Theme Into a Composer Package (Optional)

The default Magento themes are distributed in the form of Composer packages. That is why, your theme will include a composer.json file (but this is an optional step). You can copy the composer.json file from any of the Magento default themes – be it Blank or Luma.

An example of how Luma theme's composer.json file:

    "name": "magento/theme-frontend-luma",
    "description": "N/A",
    "require": {
        "php": "~5.5.0|~5.6.0|~7.0.0",
        "magento/theme-frontend-blank": "100.0.*",
        "magento/framework": "100.0.*"
    "type": "magento2-theme",
    "version": "100.0.1",
    "license": [
    "autoload": {
        "files": [

Step 6 – Final Directory Structure

Once you are done with the task of declaring and registering your theme, you are only left with creating the final directory structure for the layouts, templates and other files. Let's have a quick view of the final theme file structure:


Note: Static files like CSS, JavaScript and images, will either get stored in the skin folder of your theme. or within the etc/view.xml file. The image size of the Magento Catalog can be configured through the etc/view.xml file. 

Step 7 – Declare Your Magento 2 Theme Logo

Now, before you activate your new Magento 2 theme, you should also add your theme's logo and declare it. You can add your logo file to the web/images folder.

Next, consider creating the Magento_Theme/layout folder and insert below code to a default.xml file to make sure that your theme uses the same logo.

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <referenceBlock name="themelogo">
                <argument name="themelogo_file" xsi:type="string">images/logo.svg</argument>
                <argument name="themelogo_img_width" xsi:type="number">350</argument>
                <argument name="themelogo_img_height" xsi:type="number">350</argument>

Step 8 – Activate Your Magento 2 Theme

And at last, just activate your themefrom admin panel. Then navigate to Content → Design → Themes and check if your theme is present in the list or not. If not, then make sure that it is declared properly.

If you are able to view your theme in the above path then go to StoresConfigurationDesign. Now from the "Store View" drop-down field (consider screenshot below), choose the store view wherein you wish to apply your theme. And then, from the "Design Theme" tab, choose the new theme from the drop-down.

Magento 2 Theme Development Configuration
Magento 2 Theme Development Configuration

After selecting your theme, press the "Save config" button. To see if your theme has activated or not! Now, reload the front pages of your Magento 2 store.

Note: If you are not getting your theme correctly then do not forget to clear the cache.

Final Words

This tutorial only serves as a basic guide to applying a new Magento theme to your store. However, once your theme is installed and activated, you'll also need to consider customization as per your project requirement.