Theme Fallback Reference

Understanding the Magento 2 Theme Fallback System

The Theme Fallback Reference shows the exact order in which Magento 2 searches for templates, layouts, and web assets when rendering a page. Understanding this chain is the key to overriding third-party module files correctly — without touching the original source — and to diagnosing why a customization is or is not taking effect.

When Magento needs a file (a .phtml template, a layout XML, a CSS or JS asset), it walks through a prioritized list of directories, stopping as soon as it finds the file. Your custom theme is always checked first, then each parent theme in order, and finally the module's own view/ directory inside vendor/. The lib/web/ directory is also checked last for generic web assets.

Fallback Order for Each File Type

• Templates (.phtml) — Checked in app/design/{area}/{theme}/{Module}/templates/ for each theme level before falling back to vendor/magento/{module}/view/{area}/templates/.
• Layouts (.xml) — Merged from all levels. Unlike templates, layout files at all fallback levels are merged together, with your theme's instructions taking precedence over inherited ones.
• Web assets (CSS, JS, images) — Checked per theme level in app/design/{area}/{theme}/{Module}/web/, then app/design/{area}/{theme}/web/ for non-module assets, then the module's own view/{area}/web/.

How to Override a File

To override a template from Magento_Catalog, copy the file from vendor/magento/module-catalog/view/frontend/templates/ to app/design/frontend/{YourTheme}/Magento_Catalog/templates/ maintaining the same relative path. Magento will pick up your copy before the vendor original.

Always run bin/magento cache:clean after adding override files. In developer mode, most caches update automatically, but the full_page cache and pre-processed view files may need explicit flushing.

Common Mistakes

• Putting override files in the wrong subdirectory. The path after the module name must exactly mirror the path inside the module's view/{area}/ directory.
• Overlooking grandparent theme files. If your parent theme (e.g., Luma) already overrides a template, your grandparent theme's version is never reached — check the parent first.
• Mixing up app/design/frontend and app/design/adminhtml. Frontend and admin theme trees are completely separate.