How to Create and Maintain Template Overrides in Joomla

Why overrides exist

Every Joomla site eventually needs markup that the original template does not ship: an extra class on the login module, a restructured article header, a Read More button that matches the brand. The tempting route is to open the template’s own files and edit them. That route breaks on the next update, because an update can replace those files and quietly wipe out every change made to them.

Joomla’s answer is the override. A copy of an extension’s view file is placed in a specific folder inside your template, and Joomla uses that copy instead of the original whenever it renders that view. The core file stays untouched, the extension keeps its normal update path, and your customisation survives. If you maintain more than one client site on the platform, overrides are also the reason those sites stay maintainable — see our Joomla development service for how we apply this in practice.

Where override files live

Override files sit in the html folder of the active template. For the shipped Cassiopeia template that is templates/cassiopeia/html/. By default, that folder already contains overrides for layouts, mod_custom, mod_menu and the TinyMCE editor integration — evidence that even the core team treats the folder as the right place for customisation.

The folder names follow the extension being overridden:

• Component views live under a com_ prefix, for example html/com_content/article/default.php overrides the single-article view.
• Module layouts use the module name, so html/mod_login/default.php overrides the login module’s default layout.
• Plugin overrides start with plg_, and the second part of the folder name indicates the plugin group.

Knowing the convention matters because it works in both directions. When a page renders something you want to change, you can often find the responsible file by locating the corresponding tmpl folder in the extension’s source; when an override misbehaves, you know exactly which folder to inspect.

Creating an override from the admin UI

You do not need FTP access or a code editor to create the initial copy. Joomla builds the copy for you:

1. In the administrator backend, go to System → Site Templates and open the template’s details page — for the default template this is listed as Cassiopeia Details and Files. The form that opens is titled Templates: Customise (Cassiopeia).
2. Switch to the Create Overrides tab. It lists the Modules, Components, Plugins and Layouts available for overriding.
3. Click the extension you want to override. Joomla copies that extension’s template PHP files into the html folder and returns you to the Editor tab, where the copied files now appear. Clicking mod_login, for example, produces default.php and default_logout.php under html/mod_login/.
4. Delete the files you do not need. Select a file and use the Delete File button in the toolbar, confirming the alert dialog. The Manage Folders button removes whole folders — but only delete things you created yourself. The pre-existing overrides in the html folder are there for a reason, and removing them can change how core features render.

The copied files are ordinary PHP. Edit them in the built-in editor, or work on them directly in your development environment if you prefer a real editor with syntax highlighting.

Comparing your override with the original

The Editor tab shows two buttons at the top right of any override file: Show Original File and Show Differences. The diff view marks added lines in green and deleted lines in red.

This is not just a convenience feature. It is the backbone of long-term override maintenance, and it answers the question every site owner eventually asks: “an update just shipped — is my override still valid?” Open the override, hit Show Differences, and you can see exactly how far your copy has drifted from the version the extension currently ships. A small diff you recognise is fine. A diff full of unfamiliar lines means the upstream file changed and your copy is silently masking those changes.

Override or alternative layout?

Joomla offers two related mechanisms, and choosing the wrong one causes real confusion later:

• A template override keeps the original file name. html/mod_login/default.php replaces the login module’s default layout everywhere, on every page where that module renders. There is no option to choose whether or not to use it — it is always used. That is the right tool when you want to change how something looks across the whole site.
• An alternative layout uses a different file name in the same folder. Rename the override to html/mod_login/expires.php (with a companion expires_logout.php), and the module’s edit form gains a choice: in the Advanced tab, the Layout field now offers both “– From Module – / Default” and “– From cassiopeia Template – / expires”. That suits cases where you want two variants — the official user guide’s example is one login module for the public and another for super users, the latter showing the session expiry time.

The naming rule matters: the primary layout file should not contain underscores, while secondary files that belong to it (like expires_logout.php) do. Also note that plugins do not provide a mechanism to select alternative layouts, so plugin customisation is override-only.

One caveat with alternative layouts: once selected in the module parameters, the layout applies regardless of which template displays the page where the module appears. If the site runs multiple template styles, the alternative layout must work in all of them.

For content items, the same choice appears in the article Options tab and in global configuration, and category views work the same way — provided no menu item exists for that specific article or category, because a menu item’s own layout selection takes priority.

Menu item alternative layouts

Alternative layouts for component views used as menu items require one extra step: a matching XML file with the same base name (myarticle.php plus myarticle.xml in html/com_content/article/). The XML follows the core menu item format and lets you hide or add parameter fields. The resulting layout then appears in the menu item type selection list and behaves like a standard menu item.

Micro-layouts

Beyond whole views, Joomla renders small page elements — the Read More button, the intro image, the article title in a blog listing — through layout files invoked via LayoutHelper calls such as rendering joomla.content.blog_style_default_item_title. To find the file behind such a layout, replace the dots with slashes, prepend /layouts/ and append .php. An overridden copy goes under templates/cassiopeia/html/layouts/ following the same path. This is the surgical option: when only the article title markup is wrong, overriding the micro-layout avoids touching the whole view.

Keeping overrides healthy

Overrides trade one problem for another. You no longer lose changes to updates, but you now own files that age independently of the extension they came from. A disciplined workflow keeps that cost low:

• Keep diffs minimal. Override only what you actually change. An override that reformats the whole file makes the diff view useless and hides upstream security fixes.
• Review after every update. After a Joomla or extension update, open each override and use Show Differences against the new original. Reconcile any upstream changes worth keeping.
• Track overrides in version control. The html folder is part of the template and belongs in the repository alongside everything else. This also gives you a history of when each override changed and why.
• Translate labels properly. Layout names shown in selection lists can be translated through System → Manage → Language Overrides rather than embedding display text in the files.

These habits compound. A site whose overrides are small, reviewed and versioned takes minutes to audit; a site with bloated, undocumented overrides turns every update into an archaeology project — and becomes one of the hidden costs that make platform decisions harder than they should be, as discussed in our guide to choosing a CMS for business.

When overrides are the wrong tool

Overrides change output, not behaviour. If you find yourself rewriting database queries or business logic inside an override file, the real requirement is probably a template with a proper child structure, a small plugin, or a custom template built for the site — the trade-offs between page builders, stock templates and custom work are covered in page builder vs custom theme. And when the number of overrides starts to rival the original template, it is worth considering whether a purpose-built Joomla template would be cheaper to maintain than a stock template with fifty patches.

Overrides also need a home in your upgrade plan: before a major version change, inventory them, test each one on staging, and budget time for reconciliation. Our Joomla upgrade planning guide covers that process in detail.