If you change a Magento storefront by editing the theme you installed, you are writing code that a future update will delete. The correct pattern is a child theme: a thin theme that declares an existing theme as its parent, inherits everything from it, and holds only the files you actually changed. When the parent updates, your customizations survive — because they were never mixed into it.
The takeaway up front: create a small child theme, point its theme.xml at the parent, and override only the specific files you need. Everything else falls through to the parent automatically. This guide is the concrete version — the file structure, the one line that makes inheritance work, how to override templates, layout, and LESS safely, and how to do the same on a purchased theme.
Why a Child Theme, and Never the Parent
Magento's default themes (Luma and Blank) ship inside vendor/ or as Composer packages. Any commercial theme you buy does too. Everything under vendor/ is owned by its package: the moment you run composer update or apply the theme vendor's patch, your edits there are overwritten without warning. Editing the parent is not a shortcut — it is a debt that comes due on the next update.
A child theme solves this with theme inheritance. Magento resolves each requested file through a fallback chain: your theme first, then its parent, then the parent's parent, down to the base module. You supply only the files you change; the rest resolve to the parent untouched. That means minimal surface area, clean diffs, and updates that flow straight through. It is the difference between a customization you maintain and a fork you are trapped in.
Step 1 — Create the Theme Skeleton
A theme lives in app/design/frontend/<Vendor>/<theme>/. Pick a vendor namespace (your brand) and a theme name. Two files are mandatory.
registration.php — registers the theme with Magento's component registrar:
<?php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
ComponentRegistrar::THEME,
'frontend/Acme/storefront',
__DIR__
);
theme.xml — names the theme and, crucially, declares the parent:
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
<title>Acme Storefront</title>
<parent>Magento/luma</parent>
<media>
<preview_image>media/preview.jpg</preview_image>
</media>
</theme>
That single <parent>Magento/luma</parent> line is what makes this a child theme rather than a standalone one. Swap it for any registered theme path — Magento/blank, or a purchased theme's Vendor/theme — and you inherit from that instead.
Your starting tree looks like this:
app/design/frontend/Acme/storefront/
├── registration.php
├── theme.xml
├── media/
│ └── preview.jpg
└── web/
└── css/
└── source/
└── _extend.less
If you plan to distribute or version the theme as a package, add a composer.json with "type": "magento2-theme" and a require on the parent theme package. For a project-local theme committed to your store's repo, the two files above are enough.
Step 2 — Register and Apply the Theme
New theme files are not picked up until Magento scans for components. From the store root:
php bin/magento setup:upgrade
php bin/magento cache:flush
setup:upgrade writes the theme into the theme table so it appears in the admin. Now apply it: go to Content → Design → Configuration, edit the store view, set Applied Theme to Acme Storefront, and save. (You can also set it under Stores → Configuration → General → Design.)
Finally, generate the frontend assets. In production mode this is required after every change:
php bin/magento setup:static-content:deploy en_US --theme "Acme/storefront"
php bin/magento cache:flush
In developer mode, static files are generated on demand, but browsers and Magento cache the old ones — so after editing LESS you must clear the generated copies (pub/static/frontend/ and var/view_preprocessed/) and reload. Forgetting this step is the top reason changes seem not to work when the code is correct.
Extend vs. Override: The Rule That Keeps Updates Clean
Every customization is one of two things: extending the parent (adding on top) or overriding it (replacing a file). Choosing the lighter one keeps you inheriting the parent's future fixes.
| File type | Extend (preferred) | Override (only when needed) |
|---|---|---|
| Styles (LESS) | Add rules in web/css/source/_extend.less — merged on top of the parent |
Mirror a parent LESS file's path to replace it entirely |
| Layout (XML) | Same-name file in <Module>/layout/ is merged with the parent |
Put it in <Module>/layout/override/ to replace the parent's layout |
| Templates (.phtml) | (no merge — templates are replaced) | Copy the single file you need into your theme |
| Config (view.xml) | Copy etc/view.xml, change only the values you need |
— |
The principle: extend when the mechanism allows it, override only the smallest unit you must, and never copy a whole module. Every file you override stops receiving the parent's updates, so each one is a maintenance liability you choose to own.
Overriding Styles, Templates, and Layout
Styles. web/css/source/_extend.less is loaded automatically and appended to the parent's styles — so it is the safest place for your CSS. Add rules there and they layer on top:
// app/design/frontend/Acme/storefront/web/css/source/_extend.less
.page-header { border-bottom: 3px solid #1b4dff; }
.product-item-name { font-weight: 600; }
To retune the theme's variables (colors, breakpoints, fonts), override the specific file that defines them by recreating its path in your theme — not by editing Luma's copy.
Templates. Magento's fallback means you override a template by placing a file at the same relative path. To customize the product-list template, copy the module's original:
vendor/magento/module-catalog/view/frontend/templates/product/list.phtml
# to
app/design/frontend/Acme/storefront/Magento_Catalog/templates/product/list.phtml
Note the Magento_Catalog folder: theme overrides of module files live under a directory named for that module. Copy only list.phtml, edit it, and every other Catalog template still resolves to the parent.
Layout. A same-named layout file is merged, not replaced — so to add a block or move one, create Magento_Theme/layout/default.xml in your theme with just your changes. Use the override/ subdirectory only when you genuinely need to discard the parent's layout for that handle.
If you have not settled on a base theme to build on yet, decide that first with how to choose a Magento 2 theme — the child theme is where you make it yours afterward.
Building on Top of a Purchased Theme
Bought a multipurpose theme like Magetique, Porto, or Ultimo? The same rule applies: do not edit the theme you bought. Create your child theme with the purchased theme as its parent — for example <parent>Swissup/argento</parent> or whatever path the vendor registers. You now have a three-level chain: base → purchased theme → your child. The vendor's updates flow into the purchased theme, and yours sit safely above them.
This "grandchild" arrangement is the professional default for agency builds: the client's brand tweaks live in a tiny theme you control, the licensed theme stays updatable, and a later handoff is a short, readable set of overrides instead of an archaeology project.
Child Theme Checklist
Before you call it done, confirm each of these:
- [ ]
registration.phpandtheme.xmlexist underapp/design/frontend/<Vendor>/<theme>/. - [ ]
theme.xmlhas the correct<parent>path for the theme you are extending. - [ ]
php bin/magento setup:upgraderan and the theme shows under Content → Design → Configuration. - [ ] The theme is applied to the right store view (not just the default scope).
- [ ] Styles live in
_extend.less; only necessary files are overridden. - [ ] Overridden templates sit under a
Magento_<Module>folder at the correct path. - [ ] Static content was deployed (production) or generated files were cleared (developer), then cache flushed.
- [ ] Nothing in
vendor/or the parent theme was edited directly.
FAQ
What is the difference between a parent and child theme in Magento 2?
A parent theme is a complete theme (Luma, Blank, or a purchased one) that provides all templates, layout, and styles. A child theme declares that parent in its theme.xml and inherits everything, supplying only the files it changes. Requests fall back through the child to the parent, so the child stays small and the parent stays updatable.
Do I still need a child theme if I bought a premium theme?
Yes — arguably more so. Editing a purchased theme's files means your changes vanish when the vendor ships an update. Make your bought theme the parent and put your customizations in a child theme above it. You keep the vendor's fixes and isolate your own work.
Why aren't my CSS or template changes showing up?
Almost always a static-content problem, not a code problem. In production, run setup:static-content:deploy and flush the cache. In developer mode, clear the generated pub/static/frontend/ and var/view_preprocessed/ folders and reload. Also confirm the theme is actually applied to the store view you are viewing.
Can I override a single template without copying the whole module?
Yes, and you should. Copy only the one .phtml you need into your theme at the same relative path under a Magento_<Module> folder. Every other file in that module keeps resolving to the parent, so you inherit its future updates for everything you did not touch.
Should I use _extend.less or override the parent's LESS file?
Prefer _extend.less. It is loaded automatically and layered on top of the parent, so you add styles without breaking inheritance. Override a specific parent LESS file only when you must change something the extend file cannot reach, such as a variable's default value.
Do I have to write a composer.json for my child theme?
Not for a project-local theme committed to your store's repository — registration.php and theme.xml are enough. Add a composer.json with "type": "magento2-theme" only when you want to distribute the theme as a package or pin it to a specific parent-theme version.
Customize Without the Debt
A child theme is the small amount of discipline that pays off on every future update: declare the parent, override only what you change, and keep your hands off vendor/. Do that, and customizing Magento stops being a fight with the next upgrade and becomes a clean, readable layer you own. Explore Magetique to build a Magento storefront you can customize cleanly.
