An In-Depth Look at Magento Theme Fallback
An In-Depth Look at Magento Theme Fallback

An In-Depth Look at Magento Theme Fallback

Published August 5, 2014 in Development
Compiling Sass with Phpstorm
June 10, 2014
Avoiding Code Errors
Avoiding Coding Errors
August 25, 2014

Magento supports unparalleled theme flexibility and sophistication that allow for incredibly custom branding while still retaining development efficiency and upgrade compatibility. In particular, the theme asset fallback system allows theme developers to only modify the parts of a theme which actually need to be customized. This feature also enables merchants to quickly deploy stylized stores while still retaining features developed for the overall brand.

Current Fallback Structure

Magento Enterprise 1.14 and Community 1.9 introduced a new, more flexible theme fallback mechanism. Each theme can now specify its parent, which can then specify its parent, and so on. This theoretically allows infinite fall back levels instead of the fixed number of fall back “slots” in older versions.


As powerful as this concept is, the core code powering it is relatively straightforward.

Config Discovery

While loading the current area in a controller’s preDispatch() method, a singleton instance of Mage_Core_Model_Design_Configis instantiated. This class’s constructor scans all themes for an etc/theme.xml file, and loads the contents into a in-memory config instance.


Mage_Core_Model_Design_Config::__construct() screenshot

The contents of the theme.xml files are not yet interpreted, but the config tree is ready for when the time comes.

Fallback Determination

When a theme asset (translation, layout update file, template, etc) is loaded,Mage_Core_Model_Design_Package::getFilename() is used to determine the actual filesystem path to the file.


Mage_Core_Model_Design_Package::getFilename() screenshot

The package model tries each theme in the fallback path, then finally falls back to base/default if all else fails. The fallback path itself, however, is generated by Mage_Core_Model_Design_Fallback::getFallbackScheme() as seen below.


Mage_Core_Model_Design_Fallback::getFallbackScheme() screenshot

For compatibility with themes developed before 1.14/1.9, this method looks for the presence of a node in the design config for the current area/package/theme (which, of course, was directly populated from the contents of that theme’s theme.xml).

In the event that the theme does specify a parent node (and therefore opts-in to the new fallback logic),Mage_Core_Model_Design_Fallback::_getFallbackScheme() walks up the chain of parent nodes, starting from the current theme’s parent.


Mage_Core_Model_Design_Fallback::_getFallbackScheme() screenshot

Otherwise, _getLegacyFallbackScheme() takes over and emulates the old fallback behavior.


Mage_Core_Model_Design_Fallback::_getLegacyFallbackScheme() screenshot

This method returns a fallback path of the following form:

  1. First check the theme specified as default in System Configuration
  2. Then check the /default theme

Theme Overrides

In the event that a translation/template/skin/layout override is specified in System Configuration, the theme fallback is calculated in the same way, but the overridden file type follows an independent fallback path starting with the configured override theme.

Summary Flowchart

Considering the new theme fallback capabilities, current versions of Magento will use this fallback path to load theme asset files.

Current Magento theme fallback flowchart

Classic Fallback

Magento versions before Enterprise 1.14 and Community 1.9 used much simpler, albeit far less powerful and flexible, fallback logic.

Mage_Core_Model_Design_Package::getFilename() from Enterprise 1.13

Mage_Core_Model_Design_Package::getFilename() screenshot

Just as the legacy fallback logic used in current versions, the classic fallback logic simply checked the current theme for the given file type, the default theme set in System Configuration, the hard-coded /default theme, then finally fell back to base/default.

With this in mind, classic versions of Magento will use the following fallback path.

Classic Magento theme fallback flowchart


By allowing merchants to configure a chain of overriding themes combined with the ability to configure the current theme at the store view level, Magento provides a powerful and efficient mechanism to customize individual stores or landing pages while ensuring that core theme assets are consolidated and centralized. Additionally, Magento Enterprise 1.14 and Community 1.9 support endless flexibility and scalability by providing support for infinite levels of theme fallback.


  1. […] Eric Wiese from Classy Llama explains how the new infinite theme inheritance works internally: An In-Depth Look at Magento Theme Fallback […]

  2. Noetical says:

    Thank you for this informative post.
    BTW, all of the images in this post are missing…wanted to give you a heads–up! ;^D

    • Eric Wiese says:


      Thanks for the heads up! A recent website migration ate some of my blog images, but it’s fixed now.

  3. MagentoTina says:

    Is this working also in Magento Admin? I already have custom Admin theme app/design/adminhtml/default/mycustom created and in use. But now, for some stores, I want to use another Admin theme, which will fallback to mycustom theme. I already tried defining parent theme in etc/theme.xml, but it seems like it’s not working. Do you know why?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Most Recent PostsView all
August 30, 2022

Five Things You Should Know About eCommerce Fraud

 “Retailers declined $16 billion in legitimate orders for fear of fraud during a recent 12-month period.” — 451 Research As eCommerce has become a bigger portion […]
April 12, 2022

Full-service eCommerce Support for Ammunition Depot

Like many eCommerce brands with big growth goals, Ammunition Depot realized they weren’t on a platform that could scale along with their business. As they expanded […]
April 5, 2022

How a Full-Service eCommerce Agency Makes Your Life easier

Do you have an eCommerce business? Are you tired of dealing with multiple vendors, tech integrations, software services and more, all while trying to piece together […]