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.

✨ Vultr and Linode are back on Cloudways! VIEW PLANS→

Magento 2 Theme Development: How to Create a Custom Theme from Scratch

Updated on July 7, 2023

10 Min Read

Magento 2 themes are a core component of a consistent aesthetic and mood for the whole store. By combining custom templates, designs, styles, or images, developers 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.

Magento strongly recommends not changing or editing the default Luma and Blank theme files if you want to customize the default theme or create your theme. The latest version of Magento can overwrite the changes or edits in the default files while updating it.

In this tutorial, I’ll tell you about Magento theme development, what the requirements are, and how you can create a custom theme in Magento.

Advantages of Custom Magento Theme

Magento 2 theme controls the features and visual appearance of your store, we highly recommend creating a custom theme to bring more conversions.

The custom theme requires specific tech skills; if you have technical development experience, the Magento theme will bring additional changes to your store. Let’s explore the benefits.

  • Customization: Customize the functionality and design to your specific requirements.
  • Relevancy: The customized theme can bring and reflect your brand with additional changes.
  • Change Theme: Themes can be changed per store by creating a child theme as the parent theme.
  • SEO-optimized: To bring more conversions to your store, the custom theme can control the URL based on SEO needs, as a result, drive more traffic to the store.
  • Management: Themes created by your developers will be easier to manage.

Experience the Cloudways Magento 2 Demo Store – No tech skills needed!

Experience a fully functional Magento 2 store built on top of renowned Cloudways hosting to deliver the fastest speeds.

Requirements for Magento Theme Development

Before you begin working on developing your theme for Magento 2, make sure you fulfill the following requirements.

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.

Getting Started With Magento Theme Directory

This is a required step to understanding the theme location. Magento 2 theme directories are located under vendor/magento/theme-frontend-<theme-code> when you install Magento via Composer.

Frontend developers implement the custom Magento themes to come with packages, custom themes, or extended default theme directories located at the app/design/frontend/<Vendor>/ structure. Each theme follows the directory structure as:


├── <theme1>

├── <theme2>/

├── <theme3>



├── <mytheme1>

├── <mytheme2>/

├── <mytheme3>


Create Directory Structure in Magento Theme

A theme is a set of files; you can include HTML, CSS, and JavaScript files, modules, and additional layout files within the subdirectories of the theme module. After adding the complete theme declaration and registration, you must 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 vendor and directory name.


It will create a web folder that contains our theme’s css, js, fonts, and image files. If Magento 2 doesn’t have a skin folder, these files go in here. I have created a view.xml file under /app/design/frontend/Cloudways/m2-theme/etc/view.xml. We configure the Magento 2 Catalog image size and other things.

Need Professional Help?

We have some of the best Magento Development Agencies from all over the world on our Agency Partners Directory!

Create a Custom Magento Theme from Scratch

These are the steps for creating a custom Magento theme.

  • Step 1: Create a Theme Directory
  • Step 2: Declare Magento Theme
  • Step 3: Add Composer Package
  • Step 4: Add Registration.php File
  • Step 5: Configure Custom Theme
  • Step 6: Configure Image Properties
  • Step 7: Declare Logo in Custom Theme
  • Step 8: Inheritance of Theme
  • Step 9: Add Theme Styling
  • Step 10: Override Theme Layout

Step 1: 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 guide 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 Magento 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>Cloudways 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 thumbnail image appears in the Magento 2 admin on our theme page for preview purposes. It is located in app/design/frontend/Cloudways/m2-theme/media/m2-theme-image.jpg.

custom magento 2 theme

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.

Step 3: Add 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; the default Magento public packaging server is This file is provided in the theme dependency information. 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 File

To register your theme in Magento, 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

Step 5: Configure Custom Theme

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, Content → Design → Themes. Make sure your theme appears on this list.

When you see your theme in this list, go to Stores → Configuration → Design and select your newly created theme. After selecting your theme, click the Save Config button, as shown below.

Magento theme selection

In the next step, go to SystemCache Management → click the Flush Magento Cache button.

Step 6: Configure Image Properties

To configure 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 configuration will look like:

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

Step 7: Declare Logo in Custom 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 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 the Magento system searches through the default themes’ module files or library if a view file is not found in your custom Magento theme.

The fallback mechanism is entirely different for static files like CSS, JavaScript, fonts, images, and other theme files. A parent theme is defined in the child theme using a theme.xml file, as discussed earlier in this article.

I strongly recommend extending the Magento default themes – Luma and Blank, and not changing the files directly because updates will overwrite those changes. Apply the new theme with Luma as the parent theme, and customize the theme files accordingly.

Create a Child Theme

This is a step where you must grasp the concepts of Magento theme customization and extend the theme to minimize the development tasks. A child theme is an original copy of the parent theme that inherits all the properties of the parent theme. Developers can implement the new logic and appearance without interrupting the parent theme and losing the changes after updates.

Steps to Create Child Theme in Magento 2

Let’s get started with creating a child theme.

Step 1

Create a child theme folder with the following naming convention {parent-theme-name},_child, in the folder path:


Step 2

Create the file theme.xml in the child theme folder in the given path app/design/frontend/Cloudways/luma_child/theme.xml to specify the parent theme. This is an important step, so we set the value as Magento/Luma.

Now add the code as:

<theme xmlns:xsi=""
    <title>Cloudways Child</title>

Step 3

Create the registration.php file in the theme folder app/design/frontend/Cloudways/luma_child/registration.php to register your child’s theme.

Now paste the following code:


Step 4

Create composer.json at the given path: app/design/frontend/Cloudways/luma_child/composer.json

    "name": "cloudways/theme-frontend-luma-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": [
    "autoload": {
        "files": [

Step 5

Create a web directory inside the child theme with the following empty directories and files. The whole directory structure for the child theme looks like this:


Step 6

Provide access/permission for child theme directories and files. Go to the child theme directory in the terminal and run this command to give permissions for the child theme directory: chmod -R 777.

Step 7

The admin panel shows like this:


Hence this way, you can create a child theme in Magento 2. You can now enable the theme and customize the theme in Magento. Go to the Magento root folder in your terminal and deploy static content using the following command:

php bin/magento setup:static-content:deploy -f

Step 9: Add 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 mainly 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 if found 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. Click on the Save Config button.

Magento theme flow type

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 location: /app/design/frontend/Cloudways/m2-theme/web/css/source/cw-theme.less

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

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

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

   .cwcustom-class {
    color: blue;

You can add your theme-specific styles in this file, 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.

Step 10: Override Theme Layout

For overriding the 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:


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. Block name or alias.
  2. Page type of the parent handle.


I focused on the most important things required to create a basic custom Magento theme and extend the default theme as a child theme. I hope this guide has helped you understand everything about Magento theme development. Still. if you have any problems or are stuck at any point, please feel free to comment below.

Now that you’ve learned how to tweak your theme 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%.

Q1. What is a 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 provides two themes, one is Luma for demonstration, and the second is Blank for custom theme creation.

Q2. What is the default location of Magento themes?

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

Q3. What is the Extension of Default Magento Template Files?

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

Q4. How can I change the Magento theme?

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

  1. Log in to the Admin Panel.
  2. Go to Content → Design → Configuration.
  3. Click Edit theme.
  4. In the Applied Theme dropdown, select the theme you want to change.
  5. Click Save Configuration.
Share your opinion in the comment section. COMMENT NOW

Share This Article

Jyotishna Kumari

Jyotishina is the Magento Community Expert at Cloudways and has 4 years of experience in web development. She has worked on e-commerce sites since the turn of the millennium and was working with Magento before version 1 was released. She loves to travel and explore new ideas whenever she finds time. Get in touch with her 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!

Want to Experience the Cloudways Platform in Its Full Glory?

Take a FREE guided tour of Cloudways and see for yourself how easily you can manage your server & apps on the leading cloud-hosting platform.

Start my tour


  • 0


  • 0


  • 0


  • 0



For 4 Months &
40 Free Migrations

For 4 Months &
40 Free Migrations

Upgrade Now