Create Magento Custom Theme [Ultimate Guide]

While there is a multitude of Magento 2 themes available on the market, you might still want to create custom theme for your store. Why? Templates, layouts, graphics and styles offered in a theme don't always satisfy your business requirements. Besides, the default Magento 2 themes Luma and Blank won't suffice if you're starting an Ecommerce website.

So, to create custom Magento 2 theme that conveys your brand's "feel" you need to resort to custom development.

In this guide, we'll walk you through all steps you need to take to create a theme for Magento and cover the basics of how to override basic and theme layouts. 

Ready to start?

Before Custom Theme Development in Magento

The first important thing to remember before starting theme development in Magento is that you shouldn't change or edit the default Luma and Blank theme files. If you customize the default theme files, the update to the latest version of Magento can override your changes.

Additionally, you should learn more about the Magento theme directory.  When you install Magento 2 theme via composer, theme directories are located under vendor/vendorName/themeName.

Themes with packages, extended default theme directories, or custom themes implemented by frontend developers are located under app/design/frontend/vendorName.

And here's the folder structure you should follow:

app/design/frontend/vendorName/
├── themeName/
│   ├── etc/
│   │   ├── view.xml
│   ├── web/
│   │   ├── images
│   │   │   ├── logo.svg
│   ├── registration.php
│   ├── theme.xml
│   ├── composer.json

Steps to Create Magento 2 Custom Theme

We'll be using Magefan as a theme vendor name and custom_theme as a theme name in this guide.

1. Create theme directory

To create theme directory, go to your Magento 2 root directory/app/design/frontend and create a new theme directory there. 

Then create a directory with a theme name.

2. Declare your theme

Declaring your custom theme means letting Magento know it exists. It contains basic information about your theme.

You need to create a theme.xml file under your theme directory /app/design/frontend/Magefan/custom_theme/theme.xml and use the following code:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Magefan custom_theme</title>
        <parent>Magento/Blank</parent>
        <media>
        <preview_image>media/custom-theme-image.jpg</preview_image>
        </media>
</theme>

here:

• <title> is used to define your theme name
• <parent> is used to define parent theme, if there is one (in our case it's Blank theme)
• <preview_image> declares the theme image that appears on the theme page in the admin panel for preview purposes. (location: /app/design/frontend/Magefan/custom_theme/media/custom-theme-image.jpg)

3. Add theme composer packages

You need to create composer package to distribute your custom Magento 2 theme as a package and register it on a packaging server. For that create composer.json file in your theme directory app/design/frontend/Magefan/custom_theme/composer.json.

Use the following code: 

{
    "name": "magefan/custom-theme",
    "description": "Magefan custom_theme",
    "require": {
        "php": "~5.5.0|~5.6.0|~7.0.0",
        "magefan/custom-theme": "100.0.*",
        "magento/framework": "100.0.*"
    },
    "type": "magento2-theme",
    "version": "100.0.1",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

4. Add registration.php file

The registration.php file is required to register your theme in Magento. Create a registration.php file in your theme directory app/design/frontend/Magefan/custom_theme/registration.php, and add the following code:

<<?php
/**
* Copyright © Magento. All rights reserved.
* See COPYING.txt for license details.
*/
\Magento\Framework\Component\ComponentRegistrar::register(
\Magento\Framework\Component\ComponentRegistrar::THEME,
'frontend/Magefan/custom_theme',
__DIR__
);

5. Configure custom theme

After you add your theme to your file system, you will be able to activate it in your store. Go to Content > Design Configuration and Edit near the theme you want to apply the custom theme to and make sure you can see your custom theme on the list.

After that go to Stores > Configuration > Design and select your theme for the Design Theme. Don't forget to Save the settings.

6. Configure product image properties

If the size of product images in your custom Magento theme is different from the size of images in the parent theme, you need to create a view.xml configuration file. This file configures the size of all product images on the frontend. It is optional if it already exists in your parent theme.

To add a view.xml file you need to create an etc directory in your theme directory app/design/frontend/Magefan/custom_theme/etc. Then copy the view.xml file from the etc directory of your parent theme to your custom theme and change image properties as follows:

<image id="category_page_grid" type="small_image"> 
    <width>450</width> 
    <height>450</height> 
</image>

Here we define that we want catalogue grid images to be 450x450.

7. Create directories for theme static files

Your custom Magento 2 theme will most likely contain different types of static files like fonts, styles, images, JS, etc. Each type of static file should be stored in a web directory in your theme folder with the following structure:

app/design//Magefan/custom_theme/
├── web/
│ ├── css/
│ │ ├── source/ 
│ ├── fonts/
│ ├── images/
│ ├── js/

You need to store general theme-related static files, like theme logo in app/design/frontend/Magefan/custom_theme/web/images. If your theme contains module-specific files, they are stored in the subdirectories app/design/frontend/Magefan/custom_theme/module/web/css.

7. Declare theme logo

The default theme format and name of the logo image is logo.svg. Correspondingly, when you put this file into app/design/frontend/Magefan/custom_theme/web/images it will be automatically recognized as the theme logo and displayed in the store header after you apply the theme.

To use your custom logo you first need to declare it. However, it depends on whether your theme has a parent theme and uses its logo image. 

That being said, you don't need to declare your theme logo if you have or don't have a parent theme, but use the default naming convention — logo.svg. 

Then, if you don't use the default naming convention (regardless of whether you use a parent theme or not) you need to declare it in the layout. For that, you need to create Magento_Theme/layout directory and create the default.xml file in your theme folder /app/design/frontend/Magefan/custom_theme/Magento_Theme/layout/default.xml.

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="logo">
            <arguments>
                <argument name="logo_file" xsi:type="string">images/m2-logo.png</argument>
                <argument name="logo_img_width" xsi:type="number">300</argument>
                <argument name="logo_img_height" xsi:type="number">300</argument>
                <argument name="logo_alt" xsi:type="string">Logo name</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

How to Extend Theme Files?

If you want to make changes to your theme files, you don't have to copy the page layout or page configuration code to add modifications. Magento allows you to simply create the extending layout file with all the changes you need to add. To add extending file:

<theme_dir> 
  |__/<Namespace>_<Module> 
     |__/layout 
        |--<layout1>.xml
        |--<layout2>.xml

How to Override Theme Layouts in Magento?

If you want to override any theme layout you need to create the layout file with the same name and put it to /app/design/frontend/Magefan/custom_theme/Magento_Theme/layout/default.xml.

This will override the following layouts: 

app/design/frontend/Magefan/custom_theme/Magento_Theme/layout/default.xml

How to Create a Magento Child Theme?

Creating a child theme allows you to add some new logic and design without losing any changes after updating or interrupting the parent theme. So, basically, a child theme is a copy of the original parent theme that inherits its properties. It enables you to minimize the development task if you want to customize a theme. 

Once you learn how to create custom theme in Magento 2, you might also need to learn how to create a child theme.

1. Create a child theme folder with the name parent-theme-name_child and add it to the following directory:

app/design/frontend/Magefan/custom_theme_child

2. Create a theme.xml file in the Magento child theme folder — app/design/frontend/Magefan/custom_theme_child/theme.xml to define the parent theme, and add the following code to it:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd"> 
    <title>Magefan Child</title> 
      <parent>Magefan/custom_theme</parent> 
          <media> 
             <preview_image>media/preview.png</preview_image> 
         </media>
</theme>

3. Create registration.php filed in the child theme folder app/design/frontend/Magefan/custom_theme_child/registration.php  to register the child theme. Add the following code:

<?php 
\Magento\Framework\Component\ComponentRegistrar::register( 
    \Magento\Framework\Component\ComponentRegistrar::THEME, 
    'frontend/Magefan/custom_theme_child', 
    __DIR__ 
);

4. Create a composer.json file with the following code in app/design/frontend/Magefan/custom_theme_child/composer.json:

{
    "name": "magefan/theme-frontend-custom-theme-child",
    "description": "N/A",
    "require": {
        "php": "~5.5.0|~5.6.0|~7.0.0|~7.1.0|~7.2.0|~7.3.0|~7.4.0|~8.1.0",
        "magento/luma": "100.0.*",
        "magento/framework": "100.0.*"
    },
    "type": "magento2-theme",
    "version": "100.0.1",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

5. Create a web directory in the child theme files and add empty directories and files to it. The directory structure should be as follows: 

app/design/frontend/Magefan/
├── custom_theme_child/
│ ├── media/
│ ├── web/
│ │ ├── css/ 
│ │ │ ├── source/
│ ├── fonts/
│ ├── image/
│ ├── js/

Once you do that you'll be able to enable and customize your theme in Magento 2.

So, this is a short guide on the basics of how to create a custom theme in Magento 2. You can now extend and customize it to create the best appeal for your store, optimize the loading of certain elements and boost SEO. As long as you follow the best Magento practices you'll be able to update and extend the Magento theme without running into issues. 

You can check the file structure and theme directories example on the Github page of our Optimized Magento 2 Theme.

FAQ