This website uses cookies

Our website, platform and/or any sub domains use cookies to understand how you use our services, and to improve both your experience and our marketing relevance.

An Ultimate Guide to Magento 2 Theme Development from Scratch

Updated on December 23, 2021

8 Min Read

Magento 2 themes are a core component when it comes to a consistent aesthetic and mood for the whole store. By utilizing a combination of custom templates, designs, styles, or images development, you can improve the visual appeal of areas like the Magento 2 admin panel and storefront.

By default, there are 2 Magento themes – Luma and Blank – that you can see after successfully installing Magento 2. Luma is a demonstration theme, while Blank acts as a basis for custom Magento theme customization.

Magento 2 has no restrictions on using the Luma theme for your live store. However, if you want to customize the default design, or if you need to create your own theme, Magento strongly recommends not to change or edit the default Luma and Blank theme files. Why not? Because changes or edits to the default files can be overwritten by the latest version of the default files during your Magento 2 upgrades.

In this Magento 2 theme development series, I am going to cover the basics of frontend custom Magento 2 theme development for beginners. If you are an advanced Magento developer, you can use this to refresh your knowledge of basic concepts.

Let’s start.

Requirements for Theme Development

Before you begin work on developing your own theme for Magento 2, make sure the following requirements are fulfilled:

If you don’t have Magento 2 running, Cloudways a Magento hosting partner will have it operational easily. Launch your Magento 2 store in a matter of a few clicks and start creating your store from scratch.

Customize Your Magento Theme on a Managed Hosting Platform

Experience top-grade performance results on your custom Magento theme with an optimized hosting platform & improve your loading times dramatically.

Directory Structure in Magento 2 Theme Development

After adding complete theme declaration and registration, you need to create the directory structure for changing the Magento theme, styles and template files. Below, you can see how your theme directory should look. I am using my own vendor and directory name.

















The web folder that contains our theme’s CSS, js, fonts and images will be created. If Magento 2 doesn’t have a skin folder, these files go in here. We have created a view.xml file under the etc directory, with the view.xml file. We configure the Magento 2 Catalog images size and other things.

Step1: Create a Theme Directory

To create a directory for your Magento 2 theme, you need to go to: <your Magento 2 root directory>/app/design/frontend. 

Under the frontend directory, create a new directory according to your theme vendor name: /app/design/frontend/Cloudways (I choose Cloudways as my theme vendor name). Under your theme vendor directory, create a directory for your Magento 2 theme: /app/design/frontend/Cloudways/m2-theme.

After creating this structure, you need to declare your Magento 2 theme so that Magento knows it exists. You can set your theme as the current theme in your Magento 2 backend.

Step 2: Declare Your Magento 2 Theme

Now you need to create the theme.xml file under app/design/frontend/Cloudways/m2-theme/theme.xml and use the code below:

<theme xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd"><title>m2-theme</title>

In the <title> tag, insert the name of your theme. In the <parent> tag, you can specify the parent theme for fallback purposes. I am using the Luma theme.

I declare a theme image in the <preview_image> tag. This is a thumbnail image which shows up in the Magento 2 admin on our theme page for preview purposes. The thumbnail image is located in app/design/frontend/Cloudways/m2-theme/media/m2-theme-image.jpg

Make sure you have this thumbnail in the correct location. If you don’t have this file in the correct location, you will get an error when you visit your theme page through Magento 2 admin.

Step3: Make Your Magento 2 Theme a Composer Package

Add a composer.json file in your theme directory: app/design/frontend/Cloudways/m2-theme/composer.json to register the package on a packaging server. This file is provided in the theme dependency information. The Magento default public packaging server is Use the following code:

"name": "Cloudways/m2-theme",
"description": "Magento 2 Theme Customization",
"require": {
"php": "~5.6|~7.0|~7.1|~7.2|~7.3|~7.4",
"Cloudways/m2-theme": "100.0.*",
"magento/framework": "100.0.*"
"type": "magento2-theme",
"version": "100.0.1",
"license": [
"autoload": {
    "files": [

Step 4: Add Registration.php to Register Your Custom Magento 2 Theme Development

To register your theme in the Magento system, you need to create a registration.php file in your theme directory: app/design/frontend/Cloudways/m2-theme/registration.php and use the following code in your registration.php:

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

Magento theme navigation

Book a Personalized Cloudways Product Demo With One of Our Expert

Step 5: Apply and Configure Magento 2 Custom Theme in Admin

Once you’ve added your theme to the file system, everything is in place for you to activate your theme and apply it to your store. Go to the Magento 2 backend, then go to Content > Design > Themes. Make sure your theme appears on this list.

When you can see your theme in this list, go to Stores > Configuration > Design, select your newly created theme from those shown in the image below.

Magento theme selection

After you select your theme, click on the “Save Config” button and clear the cache.

Step 6: Configure Image Properties in Your Theme

For a configuration of catalog image sizes and other images, you need view.xml. This file is required for the theme if the product image sizes of your custom Magento theme development are different from the parent theme sizes. The view.xml file configures all storefront product image sizes. 

For example, you make the category grid view product images by specifying the size of 350 x 350 pixels. Copy the view.xml file from the etc directory of your parent theme to your theme’s etc directory. Here is what the corresponding configuration would look like:

  <image id="category_page_grid" type="small_image">

Step 7: Declare a Logo for Your Custom Magento Theme

To declare a theme logo, create Magento_Theme/layout directories and add the following code to a default.xml file. The default.xml file path is /app/design/frontend/Cloudways/m2-theme/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/m2-logo.png</argument>
<argument name="logo_img_width" xsi:type="number">350</argument>
<argument name="logo_img_height" xsi:type="number">350</argument>

I used logo filename m2-logo.png and logo size 350 x 350 pixels. You can use your own logo file name and logo size.

Step 8: Inheritance of Theme

Theme inheritance enables us to extend themes easily and minimize maintenance efforts. You can utilize a current theme as a basis for custom Magento theme development customizations, or minor store design upgrades like holiday decorations. Instead of duplicating large theme files and modifying what you need to change, you can include overriding and extending files.

Theme inheritance level is not limited in Magento 2. In Magento, theme inheritance is based on the fallback mechanism, the same as in Magento 1. This guarantees that if a view file is not found in your custom Magento theme, the Magento system searches through the default themes’ module files or library.

The fallback mechanism is entirely different for static files like CSS, fonts, images and JavaScript, and other theme files.

A parent theme is defined in the child theme using a theme.xml file, as discussed previously in this tutorial series.

Step 9: Theme Styling

Magento 2 applications use a model view controller architecture pattern. Here, the main thing we’re going to look at is styling, which mostly involves editing the CSS or LESS in this instance. Magento 2 is manufactured utilizing LESS, so this is what we are going to use to start editing the Magento 2 theme.

There are three different methods for styling the website that you should know before we begin styling the theme:

  1. Server Side Compilation
  2. Server Side Compilation Using Grunt
  3. Client-Side Compilation

I used the client-side compilation in this article, but the outcome is the same in all three methods. Before starting, uncomment a line in your .htaccess file which is shown below:

SetEnv MAGE_MODE developer

After this, we need to change the LESS compilation mode to the client-side from the Magento 2 admin panel. Go to Stores > Configuration > Advanced > Developer > Front-end development workflow > Workflow type.

Magento theme flow type

Click on the Save Config button.

In this mode, we don’t need Grunt running to compile our CSS when we refresh the web browser. The Magento system will take care of it. Now we are ready to make changes to our fewer files and see the frontend change in the following directory:/app/design/frontend/Cloudways/m2-theme/web/css/source/cw-theme.less

You can use this following code in your cw-theme.less file:

body {
   margin: 0px!important;
   padding: 0px!important;

  .page-wrapper {
   background-color: #fff;

   .cwcustom-class {
    color: blue;

In this file, you can add your theme-specific styles, save the file, and then reload your browser. With client-side compilation on, you’ll notice that there are no styles when the browser first loads. This is because Magento is compiling the LESS at the time. Give it a few seconds, and you’ll see the styles kick in, hopefully with your custom styles.

Customize Your Magento Theme on a Managed Hosting Platform

Experience top-grade performance results on your custom Magento theme with an optimized hosting platform & improve your loading times dramatically.

Step 10: Override Theme Layout

For overriding theme layout, you need to put the layout file with the same name in the following location: /app/design/frontend/Magento/luma/Magento_Theme/layout/default.xml

These files override the following layouts: /Cloudways/m2-theme/Magento_Theme/layout/default.xml

Note: For overriding page layout files, always use your directory name page_layout instead of the layout.

The layout overriding mechanism provides excellent flexibility in customization. I recommend you not to make these changes:

  1. Do not change the block name or alias.
  2. Do not change the page type of parent handle.

Frequently Ask Questions

What Is Magento Theme?

Magento theme is a combination of files including CSS, HTML, PHP, XML, and images, all of which contribute to the look and feel of an online store. Magento application provides two themes one is Luma for demonstration and the second is Blank for custom theme creation.

Where do Magento default themes reside?

Mainly, Magento theme is located under app/design/frontend//__.Other than that, built-in Magento themes can be found under vendor/magento/theme-frontend

What is the Extension of Default Magento Template Files?

A: Default Magento template files are saved with the extension of PHTML that contains all view-related logic and block classes.

How can I change Magento theme?

Here’s the quickest way to change the Magento theme via admin panel.

  1. Log in to Admin Panel.
  2. Navigate to Content > Design > Configuration.
  3. Click Edit theme.
  4. In Applied Theme dropdown, select the theme that you want to change to.
  5. Click Save Configuration.

Final Words

In this blog, I focused on the most important things required to create a basic custom theme. I hope this guide has helped you understand how to start building your Magento 2 theme. 

Now that you’ve learned how to tweak your theme as per your requirements, perhaps you’re wondering how your customized Magento store will perform. So only a highly optimized best Magento hosting platform can improve your site loading time by as much as 100%. Launch your free trial on Cloudways today.

Don’t forget to drop your queries and suggestions in the comment section.

Share your opinion in the comment section. COMMENT NOW

Share This Article

Customer Review at

“Great speed, features, knowledgebase, dashboard, UX and fast, expert support. Very happy!”

Stefan [Management Consultant]

Fayyaz Khattak

Fayyaz, a passionate Motorbike tourist, works as a Team Lead — Magento Community at Cloudways - A Managed Magento Hosting Platform. His objective is to learn & share about PHP & Magento Development in Community. You can contact him at [email protected]


Get Our Newsletter
Be the first to get the latest updates and tutorials.

Thankyou for Subscribing Us!


Webinar: How to Get 100% Scores on Core Web Vitals

Join Joe Williams & Aleksandar Savkovic on 29th of March, 2021.

Do you like what you read?

Get the Latest Updates

Share Your Feedback

Please insert Content

Thank you for your feedback!

Do you like what you read?

Get the Latest Updates

Share Your Feedback

Please insert Content

Thank you for your feedback!