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
October 15, 2021

Classy Llama Wins 2021 Comparably Awards for Best Perks&Benefits, Best Work-Life Balance

Classy Llama, Springfield’s only full-service eCommerce agency, has been placed on the top 50 list for’s Best Perks&Benefits Award, as well as their Best Work-Life […]
September 15, 2021

Classy Llama Awarded #3 Best Place to Work by Biz417

Springfield, MO — Classy Llama has been awarded the number 3 spot on the Biz417 Best Places to Work Top 20 for 2021.  This award is […]
September 13, 2021

2021 Instagram Changes: What you need to know for eCommerce Marketing

What’s Going On With Instagram in 2021? The Head of Instagram, Adam Mosseri, announced in summer 2021 that big changes are coming to the platform sometime […]