How to Create a Custom Theme in Magento 2

Introduction

Magento 2 Theme Development & Customisation – Today, we will learn how to create a custom theme in Magento 2

Magento 2 provides a powerful and flexible theming system that allows developers to customize the storefront without touching core files.

Whether you want to change styles, modify layouts, or build a completely new storefront design, creating a custom theme is the correct and upgrade-safe approach.

This blog is written in a step-by-step, beginner-friendly manner and gradually moves toward advanced concepts.

By the end, you’ll clearly understand how Magento 2 themes work and how to build one professionally.

1. How Magento 2 Theming Works (Concept First)

Before writing any code, it’s important to understand how Magento 2 themes are structured.

1.1 Theme Inheritance (Most Important Concept)

Magento 2 themes work on a parent–child model.

Instead of building everything from scratch, you usually:

Create a child theme
Extend an existing parent theme

Common parent themes provided by Magento:

Magento/blank → Lightweight, recommended for custom development
Magento/luma → Demo theme built on top of Blank

Why is inheritance useful?

You only override what you need
Core updates do not break your theme
Faster, cleaner, and optimized development

1.2 What a Theme Can Control

A Magento 2 theme can be customized:

Page structure (layout XML)
HTML output (PHTML templates)
Styling (LESS/CSS)
JavaScript behavior
Images and icons
Email templates
Translations

2. Creating the Theme Folder Structure

Magento looks for themes inside this directory: app/design/frontend/<Vendor>/<theme_name>/

Example:

app/design/frontend/Webkul/customtheme/
├── etc
│   └── view.xml
├── Magento_Theme
│   └── layout
│       └── default.xml
├── web
│   ├── css
│   ├── images
│   └── js
├── i18n
│   └── en_US.csv
├── registration.php
└── theme.xml

Don’t worry if this looks big right now — we’ll understand each file step by step.

3. Mandatory Theme Files (Required to Register Theme)

Magento will not recognize your theme unless these files exist.

3.1 theme.xml (Theme Identity)

This file defines the theme name and its parent.

app/design/frontend/Webkul/customtheme/theme.xml

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Webkul Custom Theme</title>
    <parent>Magento/blank</parent>
</theme>

3.2 registration.php (Theme Registration)

This file registers the theme in Magento.

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

3.3 view.xml (Image & Media Configuration)

Used to define image sizes used across the storefront.

<view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/view.xsd">
    <media>
        <images module="Magento_Catalog">
            <image id="category_page_grid" type="small_image">
                <width>300</width>
                <height>300</height>
            </image>
        </images>
    </media>
</view>

4. Activating the Theme in Admin Panel

After creating files, Magento needs to register them.

4.1 Run Required Commands

php bin/magento setup:upgrade
php bin/magento cache:flush

4.2 Apply Theme from Admin

Go to Admin → Content → Design → Configuration
Select Store View
Choose Webkul Custom Theme
Save configuration

5. Understanding Layout XML (Page Structure Control)

Layout XML decides what blocks appear on a page and where.

Think of layout XML as the blueprint of a page.

5.1 Global Layout Changes

File:

Magento_Theme/layout/default.xml

Example (remove compare link):

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <remove name="compare-link" />
    </body>
</page>

5.2 Page-Specific Layout Files

Magento loads layout XML based on routes.

Common examples:

Home page → cms_index_index.xml
Product page → catalog_product_view.xml
Category page → catalog_category_view.xml

6. Overriding PHTML Templates (HTML Customization)

Templates control HTML output.

6.1 Correct Way to Override Templates

Locate original template in:

vendor/magento/module-*/view/frontend/templates

Copy it to your theme:

app/design/frontend/Webkul/customtheme/<Module_Name>/templates/

Never edit files inside vendor/.

7. Styling in Magento 2 (LESS Made Simple)

Magento uses LESS, not plain CSS by default.

7.1 Important LESS Files

web/css/source/
├── _variables.less   → Override default colors, fonts
├── _extend.less      → Add your custom CSS

7.2 Add Custom Styles

.page-title {
    font-size: 26px;
    font-weight: 600;
}

8. Adding JavaScript in Theme

Magento uses RequireJS for JS loading.

8.1 requirejs-config.js

var config = {
    map: {
        '*': {
            customJs: 'js/custom'
        }
    }
};

8.2 Custom JS File

define(['jquery'], function ($) {
    'use strict';
    return function () {
        console.log('Custom theme JS loaded');
    };
});

9. Static Content & Modes (Very Important)

Developer Mode (During Development)

php bin/magento deploy:mode:set developer

Faster
No static deploy needed

Production Mode (Live Website)

php bin/magento deploy:mode:set production
php bin/magento setup:static-content:deploy

10. Translations (Multi-Language Support)

Create CSV file: i18n/en_US.csv

“Add to Cart”, “Add to Basket”

11. Email Template Overrides

You can override transactional emails.

Path: Magento_Email/email/

Examples:

Order confirmation
Customer registration

12. Performance & Best Practices

✔ Extend Magento/blank
✔ Prefer layout XML over template overrides
✔ Keep logic out of PHTML files
✔ Minimize JS and CSS
✔ Test in production mode

13. Common Beginner Mistakes

✖ Editing vendor files
✖ Hardcoding URLs
✖ Too many template overrides
✖ Ignoring cache/static content

Conclusion

Creating a custom theme in Magento 2 is not difficult once the fundamentals are clear.

By understanding theme inheritance, layout XML, LESS, and proper overrides, you can build clean, scalable, and upgrade-safe storefronts.

This blog gives you a complete guide for creating a custom theme in Magento 2 Services — from folder structure to production best practices.

If you require technical support, feel free to email us at support@webkul.com

Additionally, explore a wide array of solutions to boost your store’s capabilities by visiting our Adobe Commerce modules section and Adobe Commerce marketplace addons.

Or looking to improve your store’s speed and overall performance? Check out our Magento 2 Speed & Optimization services.

Get expert support and build customized solutions by hiring skilled Adobe Commerce developers for your project.

Categories: Magento 2

Ashish Kumar 17-December-2025

View Comments Comment or Ask a Question

Quick Links