Magento 2: Create New Theme

A quick post to show you how to create a new theme in Magento 2. Perfect when getting started with Magento 2. This post assumes you have an installation already setup and your looking to make your own customisations.

Step 1: Folder structure

Create a new directory for your theme:

app/design/frontend/<VendorName>/<ThemeName>

As a best practice the <VendorName> is usually named after the company or author building the theme and the <ThemeName> is a name of your choosing.

Step 2: Declare your theme

To declare your theme, in your theme directory add a new file called theme.xml with the following content:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Theme Name</title> <!-- your theme name, appears in the admin area -->
    <parent>Magento/blank</parent> <!-- the parent theme, in case your theme inherits from an existing theme -->
    <media>
        <preview_image>media/preview.jpg</preview_image> <!-- the path to your theme's preview image -->
    </media>
</theme>

The parent theme is used for inheriting files from an existing theme. If your theme does not include a file Magento requires it will work through the fallback hierarchy starting at your parent theme specified here.

A parent theme is not a required parameter, if no parent theme is supplied it will fallback to Magento core files under vendor/magento.

Magento 2 includes default themes named Magento/blank and Magento/luma which are popular choices to fallback to. You can read up about the theme inheritance within the Magento documentation.

The preview image is shown when viewing your themes from the admin area under Content > Design > Themes. Place the image in the following location:

app/design/frontend/<VendorName>/<ThemeName>/media/preview.jpg

The recommended image dimensions are 800 x 800.

Step 3: Register your theme

To register your theme, in your theme directory add a new file called registration.php with the following content:

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::THEME,
    'frontend/<VendorName>/<ThemeName>',
    __DIR__
);

Step 4: Create your Composer package (optional)

Magento distributes it’s themes as Composer packages, if you want to distribute your theme in this way you need to add a composer.json file to your theme directory and register the package on a packaging server. Packagist support both public and private solutions.

An example of a theme composer file:

{
    "name": "vendorname/theme-name",
    "description": "Theme description",
    "require": {
        "php": "~5.5.0|~5.6.0|~7.0.0",
        "magento/theme-frontend-blank": "100.0.*",
        "magento/framework": "100.0.*"
    },
    "type": "magento2-theme",
    "version": "1.0.0",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

The Composer file also defines theme dependency details such as what PHP version it supports along with any parent theme it requires.

Step 5: Configuring Magento catalog (optional)

To configure catalog images along with other settings you will need to add a new file within your theme directory:

app/design/frontend/<VendorName>/<ThemeName>/etc/view.xml

For the contents of this file, copy the contents of view.xml from an existing theme to your new file. For example you could copy from the Blank or Luma themes which are available from:

vendor/magento/theme-frontend-blank/etc/view.xml
vendor/magento/theme-frontend-luma/etc/view.xml

You can then configure the necessary settings to suit your needs.

Step 6: Change your logo (optional)

One of the first visual customisations might be to change your logo. To do this within your theme directory add a new file called default.xml

app/design/frontend/<VendorName>/<ThemeName>/Magento_Theme/layout/default.xml

Add the following contents and edit to suit your needs:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="logo">
            <arguments>
                <argument name="logo_file" xsi:type="string">images/logo.svg</argument>
                <argument name="logo_img_width" xsi:type="number">100</argument>
                <argument name="logo_img_height" xsi:type="number">100</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Step 7: Activate your theme

Now everything has been setup, all that’s left to do is activate your theme. Within the admin area head over to Content > Design > Configuration and select “Edit” under the store you wish to change.

From here you will be able to select your new theme from the “Applied Theme” dropdown. Once saved you may need to clear the Magento cache to see your changes applied to the front-end, this can be achieved under System > Tools > Cache Management.

Your final folder structure should look something similar to this:

app/design/frontend/<VendorName>/<ThemeName>/
app/design/frontend/<VendorName>/<ThemeName>/etc/view.xml
app/design/frontend/<VendorName>/<ThemeName>/Magento_Theme/layout/default.xml
app/design/frontend/<VendorName>/<ThemeName>/media/preview.jpg
app/design/frontend/<VendorName>/<ThemeName>/web/images/logo.svg
app/design/frontend/<VendorName>/<ThemeName>/composer.json
app/design/frontend/<VendorName>/<ThemeName>/registration.php
app/design/frontend/<VendorName>/<ThemeName>/theme.xml

Overall there are only 3 steps required as a bare minimum to register your new theme in Magento 2. There is a lot more to customise a theme but hopefully this have given you a starting point into Theme development with Magento 2.