How to Create a Magento 2 Child Theme

Why Use a Child Theme?

A child theme lets you customize your Magento 2 storefront while inheriting all assets from a parent theme. Because you never touch the parent files directly, core and third-party updates can be applied without overwriting your work.

Quick Navigation

• Step 1: Choose the Parent Theme
• Step 2: Create the Directory Structure
• Step 3: Create theme.xml
• Step 4: Create registration.php
• Step 5: (Optional) composer.json
• Step 6: Inherit & Override Assets
• Step 7: Enable & Apply the Theme
• Step 8: Verify & Troubleshoot

Step 1: Choose the Parent Theme

Pick the parent you want to extend -- for example Magento/blank or a third-party theme. Using Magento/blank gives you maximum flexibility.

Step 2: Create the Directory Structure

Create your theme folder under:

app/design/frontend/<Vendor>/<ChildTheme>

Example:

app/design/frontend/MyCompany/CustomTheme

Replace MyCompany and CustomTheme with your own vendor and theme names.

Step 3: Create theme.xml

Place this file at app/design/frontend/MyCompany/CustomTheme/etc/theme.xml:

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

Make sure the <parent> value matches the identifier of the parent theme you chose in Step 1.

Step 4: Create registration.php

Place this at the theme root -- app/design/frontend/MyCompany/CustomTheme/registration.php:

<?php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
  ComponentRegistrar::THEME,
  'frontend/MyCompany/CustomTheme',
  __DIR__
);

The path passed to ComponentRegistrar::register must match your folder structure exactly.

Step 5: (Optional) composer.json

Adding a composer.json allows Composer-driven installations:

{
  "name": "mycompany/customtheme",
  "description": "Magento 2 Child Theme",
  "require": {
    "php": "~8.1.0",
    "magento/theme-frontend-blank": "100.0.*"
  },
  "type": "magento2-theme",
  "version": "1.0.0",
  "autoload": { "files": ["registration.php"] }
}

Adjust the PHP version and parent dependency to match your environment.

Step 6: Inherit & Override Assets

Override Styles

Create web/css/source/_extend.less:

// app/design/frontend/MyCompany/CustomTheme/web/css/source/_extend.less
.button { background-color: #F0582A; }

Override Templates

Copy the module template you want to change, keeping the same relative path:

app/design/frontend/MyCompany/CustomTheme/Module_Name/templates/file.phtml

Preserving the directory hierarchy is essential for the override to take effect.

Step 7: Enable & Apply the Theme

Run these commands from the Magento root:

php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Then in the Admin panel navigate to Content > Design > Configuration and select your new theme.

Step 8: Verify & Troubleshoot

Clear both browser and Magento caches, then refresh the storefront. If styles or templates do not appear, confirm that static content was deployed and caches were flushed.

Always back up your work and test in a development environment before deploying changes to production.