Creating a custom Magento 2 theme involves several steps. Here’s a comprehensive guide to help you set up a new Magento 2 theme:

1. Directory Structure

Create the directory structure for your theme in app/design/frontend. The structure should follow this pattern:

app
└── design
    └── frontend
        └── VendorName
            └── ThemeName
                ├── etc
                ├── media
                ├── web
                │   ├── css
                │   ├── fonts
                │   ├── images
                │   ├── js
                │   └── ...
                ├── Magento_Theme
                │   ├── layout
                │   └── templates
                └── registration.php
  • VendorName: Replace this with your custom vendor name.
  • ThemeName: Replace this with your custom theme name.

2. Create theme.xml

Create theme.xml in app/design/frontend/VendorName/ThemeName/etc:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Your Theme Name</title>
    <parent>Magento/blank</parent> <!-- You can set 'Magento/luma' if you want to extend Luma -->
</theme>

3. Create registration.php

Create registration.php in app/design/frontend/VendorName/ThemeName:

<?php
use MagentoFrameworkComponentComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/VendorName/ThemeName',
    __DIR__
);

4. Add a composer.json File (Optional)

If you want to use Composer for managing your theme, add a composer.json file in the theme root:

{
    "name": "vendorname/themename",
    "description": "Magento 2 custom theme",
    "type": "magento2-theme",
    "version": "1.0.0",
    "require": {
        "php": "~7.3.0||~7.4.0||~8.1.0"
    }
}

5. Create preview.png

Place an image called preview.png in app/design/frontend/VendorName/ThemeName/media to display in the Magento admin panel.

6. Customize Layouts and Templates

  • Layout: Add .xml layout files in app/design/frontend/VendorName/ThemeName/Magento_Theme/layout. For example, to customize the homepage, create cms_index_index.xml.
  • Templates: Add .phtml template files in app/design/frontend/VendorName/ThemeName/Magento_Theme/templates.

Example layout XML file (cms_index_index.xml):

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="MagentoFrameworkViewElementTemplate" template="Magento_Theme::custom.phtml" />
        </referenceContainer>
    </body>
</page>

7. Add Custom Styles and Scripts

  • CSS: Place your custom CSS in app/design/frontend/VendorName/ThemeName/web/css/styles.css.
  • JS: Add JavaScript files in app/design/frontend/VendorName/ThemeName/web/js/.

Link the CSS in default_head_blocks.xml or include it using requirejs-config.js.

8. Deploy the Static Content

Run the following command to deploy your theme’s static content:

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

9. Enable the Theme

  1. Go to Content > Design > Configuration in the Magento admin panel.
  2. Select the store view you want to apply the theme to.
  3. Choose your theme from the Applied Theme dropdown and save the configuration.

10. Clear Cache

Run the following command to clear the cache:

php bin/magento cache:clean

Tips for Customization

  • Inheritance: If you want to build upon the existing Luma or Blank theme, specify it in the <parent> tag of theme.xml.
  • Override Files: To override core files, copy them from the parent theme to your theme directory, maintaining the same path.

That's it! Your custom Magento 2 theme should now be up and running.