Themes

A theme is a component of application which provides a consistent look and feel (visual design) for entire application area (for example, storefront or Admin) using a combination of custom templates, layouts, styles or images.

Themes are designed to override or customize view layer resources, provided initially by modules or libraries. Themes are implemented by different vendors (frontend developers) and intended to be distributed as additional packages for the system similar to other components.

Out-of-the-box application provides two design themes: Luma, as a demonstration theme, and Blank as a basis for custom theme creation.

There are no restrictions on using the demonstration Luma theme for a live store, but if you want to customize the default design, you need to create a new theme. We strongly recommend not to change the default Luma and Blank theme files, because if you do edit the default files, your changes can be overwritten by the new version of the default files during upgrades.

Your new theme can be a standalone new theme, or it can inherit from the default or any other existing one. The theme inheritance concept implemented in the system allows you to change only certain theme files.

Create basic theme files

In the <magento_root>/app/design/frontend/<Your_Vendor>/<your_theme> directory, create the following files:

• theme.xml
• registration.php
• (optionally) composer.json

How to Apply the theme

1. In the Admin Panel, go to CONTENT > Design > Configuration
2. Find the record corresponding to your store view and click Edit.
3. In the Applied Theme drop-down, select your newly created theme.
4. Click Save Configuration.

Declare your theme

After you create a directory for your theme, you must create theme.xml containing at least the theme name. Optionally, you can specify the parent theme name (if the theme inherits from one) and, if necessary, where the theme preview image is stored.

1. 1. Add or copy from an existing theme.xml file to your theme directory app/design/frontend/<Vendor>/<theme>.

   2. Configure it using the following example:

      
2. Add the preview.jpg file to the app/design/frontend/<Vendor>/<theme>/media/ directory.If you do not have a preview image for your theme, remove the <media> node:

Add registration.php

<?php

use \Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(ComponentRegistrar::THEME, ‘frontend/<Vendor>/<theme>’, __DIR__);

Theme inheritance

Theme inheritance enables you to easily extend themes and minimize the maintenance efforts. You can use an existing theme as a basis for customizations, or minor store design updates, like holidays decoration. Rather than copy extensive theme files and modify what you want to change, you can add overriding and extending files.

The level of theme inheritance is not limited.

Theme inheritance is based on the fallback mechanism, which guarantees that if a view file is not found in the current theme, the system searches in the ancestor themes, module view files or library.

The fallback order is slightly different for static assets (CSS, JavaScript, fonts and images) and other theme files, layouts and templates. The article describes the fallback for each type of theme files, and provides an overview of how to override ancestor themes and module designs.

For comprehensive information about developing theme components, see subsequent chapters in this guide.

Relationship between parent and child themes

• A child theme inherits view configuration, templates, layouts, and static file from its parents.

• A child theme is used first, whereas the parent theme is only indirectly active; its static file, layout, templates will be used if not overridden by the child theme.

• Any theme can be chosen to display, whether or not it specifies a parent theme in theme.xml.’

Override static assets

Static assets, or static view files, are styles, JavaScript, images, and fonts.To customize static view files defined in the parent theme, module view, or library files, you can override them by adding a file with the same name in the relevant location according to the fallback schemes described further. This also refers to the .less files, which technically are not static assets.

The particular directories, where the system searches in the course of the fallback, depend on whether module context is known for file. Following are the descriptions of both options.

If module context is not defined for a file:

1. Current theme static files for a specific locale (the locale set for the storefront): <theme_dir>/web/i18n/<locale>

2. Current theme static files: <theme_dir>/web/

3. Ancestor’s static files, recursively, until a theme with no parent is reached:

   • <parent_theme_dir>/web/i18n/<locale>
   • <parent_theme_dir>/web/

4. Library static view files: lib/web/

If module context is defined for a file:

1. Current theme module static files <theme_dir>/<Namespace>_<Module>/web/. Example: app/design/frontend/SampleCompany/orange/Magento_Catalog/web/

2. Ancestor themes module static files, recursively, until a theme with no ancestor is reached:

   • <parent_theme_dir>/web/i18n/<locale>/<Namespace>_<Module>
   • <parent_theme_dir>/<Namespace>_<Module>/web/

3. Module static view files for the frontend area: <module_dir>/view/frontend/web/

4. Module static view files for the base area: <module_dir>/view/base/web/