Building a Magento 2 theme for your eCommerce store

February 28, 2017 by Leah Na'aman

Every retailer wants an eCommerce store that looks great and stands out from the competition. There are out-of-the-box Magento 2 theme options, but as with most ‘one size fits all’ approaches, you’re going to find yourself limited. if creative freedom is your goal, it’s important to become familiar with the Magento 2 theme building process.

This week, we’re running through the basics of building a Magento 2 theme, so you know what to do…

Magento 2’s Out of the Box Themes: Luma & Blank

The Magento 2 platform comes with two built-in theme options – Luma and Blank. These are enough to get your store up and running with Luna providing a working theme and Blank providing the foundation for custom theme creation.

However, the drawback of using those built-in options is that you’re restricted if you want get more creative.  The reason is that any alterations made to the default files of Luma and Blank will be overridden during upgrades.

So, what to do?

If you want to get creative with your design, you’ll need to build your own Magento 2 theme.

The 10 steps to creating your own Magento 2 theme

The process is manageable for anyone with basic coding experience and our 10-step guide. First, you’ll need to ensure Magento 2 is installed correctly and working smoothly. Once this is done, log in so you have access to the backend and frontend and proceed with the below steps…

Step 1: Create a theme directory

To get started, you’ll need to create a directory for your new theme. This should be done under the frontend directory <your Magento install dir>/app/design/frontend and your directory should be created according to your vendor name: /app/design/frontend/<VendorName>.

In your new VendorName directory, create another directory for your theme, keeping file names consistent: /app/design/frontend/VendorName/theme.

Step 2: Declare your theme

After Step 1 has been completed, you’ll need to declare your theme so you can make it active in the backend. To do this, create a theme.xml file as follows: /app/design/frontend/VendorName/theme/theme.xml.

Under this, you can place the following code:

<theme xmlns:xsi=”” xsi:noNamespaceSchemaLocation=”urn:magento:framework:Config/etc/theme.xsd”>

     <title>YOUR THEME’S NAME</title>

     <parent>Magento/Luma</parent> [if your new theme is inheriting from one of Magento’s existing themes. For example, if working from Blank, replace Luma with Blank in the code.]


         <preview_image>media/YOUR IMAGE FILE.jpg</preview_image>



Step 3: Make your theme a Composer package

Adding a composer.json file allows you to register your new theme on a packaging server. Magento distributes its themes as Composer packages with as its default packaging server.

This can be done as follows: app/design/frontend/VendorName/theme/composer.json

Magento’s official documentation gives the below as an example of a composer.json theme file code:


“name”: “magento/theme-frontend-luma”,

“description”: “N/A”,

“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”: “100.0.1”,

“license”: [




“autoload”: {

“files”: [




Step 4: Add registration.php

Next, you’ll need to register your new theme in the Magento system, which is done by creating a registration.php file.

Create the following in your theme’s directory: app/design/frontend/VendorName/theme/registration.php

Then add the below code, taking care to sub in the appropriate information for VendorName and the theme code for <theme>.



 * Copyright © 2015 Magento. All rights reserved.

 * See COPYING.txt for license details.







Step 5: Configure images

Image properties, such as size, can be configured in view.xml file. If you’re using a parent theme and this already exists, you can skip the step, but if not, creating one is a requirement.

To create a view.xml file, you’ll first need to create the etc directory in your theme folder. Then copy view.xml from the Blank or Luma theme’s directory and paste it into your new theme’s etc directory. Here, you can make any alterations you need, using Magento’s official guide.

Step 6: Create directories for static files

Static file types, like fonts, images and JavaScript should be kept in separate web sub-directories in your theme folder.

Structure is as follows: /app/design/frontend/VendorName/web and then /css, /fonts, etc. as needed.

At this point in your theme creation journey, your theme’s file structure should look something like this:


├── etc/

│   ├── view.xml

├── web/

│   ├── images

│   ├──css

│   │   ├── fonts

│   │   ├── js

├── registration.php

├── theme.xml

├── composer.json

Step 7: Theme logo

logo.svg is the default format for a logo image in Magento’s directory system. When you put an image in the app/design/frontend/VendorName/theme/web/images directory, the system will log this as the official theme logo, which will then be displayed in the store page header.

In your new theme, you may need to declare your logo file if you’re using one with an alternative name or format.

Step 8: Theme registration

Opening or reloading a Magento Admin page after adding your new theme’s files to the files system will result in it being added to the database and registered.

Step 9: Apply a theme

Once Step 8 has been completed, you’ll be able to apply your newly created theme to your eCommerce store.

To do this, you’ll need to complete the following:

  • Select Content in the Admin section of your dashboard, navigate to Design and then select Configuration.
  • Find the active configuration record and select Edit.
  • In Default Theme, you’ll find your new theme in the Applied Theme dropdown menu. Select this and then click Save.
  • If you have enabled cache, be sure to clear it after saving.

Step 10: Add a design exception

If you want certain user-agents (software acting on behalf of a user) to see a different theme, you can set a design exception rather than creating separate store view. Remaining in your active store view configuration record…

  • Select Edit and click Add New User Agent Rule on the Design Rule
  • Specify the user-agent in the Search String box and select your chosen theme in the Theme Name drop-down menu.
  • Save and clear cache if necessary.


And there you have it! If you use our guide to build your own Magento 2 theme, we’d love to see what you come up with, so get in touch.




You may Also Like