Magento theme hiearachy


Magento themes follow a type of fallback hierarchy which is very similar to cascading in CSS. That means that there is one base theme (by default this is /app/design/frontend/base/default theme) that can handle any detail in a Magento site and there are one or more user defined themes that can override some or all parts of the base theme.

Assigning custom themes

Admin-defined themes are set in Magento admin panel. There are a few ways to set user themes. You can

  1. set custom design in System > Design tab or
  2. set the theme in System > Configuration > Design

First method should be used only for short term design changes such as holiday inspired themes or some other short therm event. By using the second method you can add your own default theme that can be used to look up features that cannot be found in your custom theme. Then you can have: User theme > User default theme > Base default theme. Any design resource (phtml templates, xml layouts, translations, css, JavaScript, images) are looked up in this order.

You can also be more specific by setting user themes on lower level. You can set custom design by category, by product bases. You can set custom theme for each CMS page separately. Setting custom theme for category also gives the option to set that theme for all subcategories and/or products. The lower level you set a theme the more precedence it takes. Just like CSS.

If an admin sets theme in System > Configuration > Design and then applies custom design in System > Design the latter takes precedence and overrides any System > Configuration > Design settings for the store.

If you define custom design on the lower levels mentioned above, it will override store design at that level.


Let’s see how Magento processes installed custom theme files. For instance, if category listing page calls for a template called view.phtml (in which case this template becomes a required file), but the application is unable to find the file in the theme highest in hierarchy, it will look to the next theme highest in hierarchy to find the file. Should this fail, it will continue working down the hierarchy of themes until it’s able to locate the file called view.phtml, upon which the application will load it to the store and terminate the search. This method of building design is called fallback, because the application “falls back” to the next possible source of required files in order to retrieve and load it.

Note. The theme highest in hierarchy is the theme that you assign through the System > Configuration > Design, and the theme lowest in hierarchy is the theme called default in base package that Magento automatically loads into the store. Highest theme may be overridden with lower level design settings.

Let’s say you have three themes assigned to your store and each of these themes contain the following files:

base/default My theme 1 My theme 2
All required files templates/3-col-layout.phtml templates/3-col-layout.phtml
css/base.css css/base.css

Let’s also assume that the three themes are assigned this hierarchy:

HIGHEST My theme 2 set as store theme in admin
My theme 1 set as user default theme
LOWEST default default magento theme

At close observation, you’ll see that there are few redundant files such as templates/3-col-layout.phtml and css/base.css

What does this mean?
Well, let us remind you that the files in above table are how you see the files in each theme folders and not how Magento sees it.

Magento sees the same file structure like this:

base/default My theme 1 My theme 2
All required files templates/3-col-layout.phtml

You’ll notice how Magento ignores the version of the redundant file lower in hierarchy and recognizes only the version higher in hierarchy. This is because it’s already found the required file and need not search for it any longer, therefore terminating the search for that specific file while continuing the search for other required files yet to be found.

Further reading

This post is a high level overview to help skilled programmers understand the basics of theme hierarchy in Magento. You need to read current Magento documentation for more detailed information.

See also: