Creating a layout override (alternative layout) in Joomla

Take precise control of your Joomla 6 site's design by creating layout overrides — without ever touching core files.

Joomla remains one of the most capable open-source content management systems available in 2026. Web agencies, enterprises, online shops, bloggers, community organisations, NGOs, schools, charities, and governments all rely on it as their CMS of choice. Its longevity is no accident: Joomla is built by the people who use it every day, which shows in its security track record, robust architecture, and thoughtful developer experience.

One of Joomla's most powerful — and often underused — features is its override system. A layout override lets you customise the output of templates and extensions without modifying core files. That means when Joomla 6 pushes an update, or an extension developer ships a new release, your customisations survive intact. No patching, no re-applying changes, no breakage.

TL:DR – This article walks through the step-by-step process of creating a layout override in Joomla 6 and explains how it gives developers full, maintainable control over a site's design. One important distinction before we start: this is about layout overrides, not template overrides. They are related but different things, and conflating the two is a common source of confusion.

Understanding the Purpose of Layout Overrides

Why Use Layout Overrides in Joomla

Joomla's architecture relies on templates, modules, and components working together to define how content is rendered. The default layouts are sensible starting points, but they rarely match the precise design requirements of a real project. Layout overrides solve this by giving you a sanctioned, structured way to change what gets rendered and how — without forking core code.

With Joomla 6, the override system has matured considerably. The administrator interface now surfaces override status more clearly, flagging files that have drifted out of sync with their upstream originals after an update. This means you can audit your overrides at a glance rather than hunting through directories to find what might have broken after an upgrade.

Benefits of Using Layout Overrides for Customisation

The primary benefit is update safety. Edits made directly to core template files are wiped out the moment Joomla or an extension updates. An override file lives in your template's directory, untouched by the update process. Beyond safety, overrides encourage a modular development workflow: each customisation is isolated, documented by its location, and easy to remove or revise. They also reduce the need for heavyweight third-party extensions that exist solely to change the appearance of something Joomla already renders natively.

Prerequisites for Creating a Layout Override

Ensuring Your Joomla Installation is Ready

Before creating any override, confirm that your Joomla 6 installation is healthy and that you have administrator access. You will also need either FTP access, an SSH connection, or access to your host's file manager to navigate the server's directory structure. Check that your user account has write permissions in the active template's directory.

Familiarising Yourself with Joomla's Template System

Joomla templates control visual presentation, and within each template, layout files define the output of specific components and modules. In Joomla 6, templates follow a well-defined folder hierarchy. The html subfolder inside your active template is where all override files live. Spending a few minutes exploring this structure — even before writing a single line of code — will save significant time later.

Tools You Will Need

You can edit override files directly inside the Joomla administrator under System → Templates → Site Templates, where the built-in editor now shows a diff view comparing your override against the original. For anything beyond minor tweaks, a proper code editor makes the work considerably faster and safer. Visual Studio Code is the most widely used option in 2026 and has excellent PHP and HTML support. Sublime Text remains a solid alternative. If you work on macOS, BBEdit's native SFTP integration lets you open and edit remote layout files as though they were local — a genuine time-saver on live projects. Whichever editor you choose, a working knowledge of HTML, PHP, and Joomla's templating conventions will help you make meaningful changes rather than just cosmetic ones.

Locating the Template Files for Override

Accessing Template Files in Joomla

Joomla stores its template files under the /templates/ directory at the site root (for front-end templates) and /administrator/templates/ for back-end templates. Navigate to this directory via FTP, SSH, or your host's file manager, then open the folder for the template your site is actively using. Inside, you will find a structured set of subdirectories containing assets, language files, and — crucially — the html folder where overrides are placed.

Identifying the Correct Files to Override

The override files you create must mirror the path of the originals. If you want to override the layout for a specific module, locate that module's view files in /modules/mod_example/tmpl/, then replicate the path inside your template's html folder: /templates/your-template/html/mod_example/. For components, the same logic applies: the component's view files live in /components/com_example/views/, and your overrides go in the corresponding path under /templates/your-template/html/com_example/. Getting this path exactly right is the most common stumbling block for developers new to overrides.

Understanding the Structure of Joomla Template Files

Joomla layout files mix PHP and HTML, using Joomla's JLayout system to separate logic from presentation where possible. Each view typically consists of a default.php file (the main output) alongside optional sub-template files for specific rendering scenarios. Understanding which file controls which part of the output is easier if you enable Joomla's debug mode temporarily — it annotates the front end with module and component boundaries, making it straightforward to trace rendered output back to its source file.

Copying the Original Layout for Override

Step-by-Step Guide to Copying Joomla Template Files

The process is deliberate: copy, don't move. You are creating a new file in your template's override directory that Joomla will prefer over the original. Here is the sequence:

• Identify the original layout file you want to override (for example, /modules/mod_articles_latest/tmpl/default.php).
• In your active template's html folder, create a matching subdirectory if it does not already exist (for example, /templates/your-template/html/mod_articles_latest/).
• Copy the original default.php into that new directory.
• Leave the original file completely untouched.

Joomla's override discovery mechanism will now automatically use your copy whenever that module or component renders. No additional configuration is required for the override to take effect — Joomla checks the template's html directory first.

Best Practices for File Management during the Override Process

Keep your override directory tidy. Use the same naming conventions as the originals, avoid adding files that are not genuine overrides, and — particularly on team projects — commit your template directory to version control. A Git repository containing your active template means every override change is tracked, attributable, and reversible. Add a brief comment at the top of each override file noting what was changed and why; future developers (including your future self) will thank you.

Modifying the Layout Files

What You Can Change in a Template Override

Once your override file is in place, open it in your editor and start modifying. Common changes include restructuring the HTML markup, reordering content blocks, adding or removing wrapper elements, injecting custom CSS classes, and conditionally displaying content based on Joomla's data objects. You have broad latitude over the presentation layer. What you should approach carefully is the PHP logic: Joomla's API calls and data-fetching code embedded in layout files should generally be left intact unless you have a clear reason to change them and understand the downstream effects.

Key Elements of Joomla Layouts: Modules, Components, and Views

Modules handle discrete content blocks — navigation menus, login forms, banners, article lists — and their layouts tend to be compact and self-contained. Components manage richer content types such as articles, contacts, and e-commerce catalogues, and their view structures are correspondingly more complex, often involving multiple sub-templates for list, detail, and form views. Knowing which element you are overriding shapes how you approach the edit: a module override might be a dozen lines; a component view override could span several files.

Testing Your Changes for Functionality and Design Consistency

Test thoroughly before considering any override complete. Check the output across multiple browsers and screen sizes, confirm that interactive elements still function correctly, and verify that no PHP warnings or errors appear in the debug output. It is also worth testing with Joomla's cache disabled during development — cached output can mask problems and make it appear that changes have not taken effect when they have, or vice versa.

Applying and Activating the Layout Override

How to Activate the Override in Joomla's Admin Panel

For most overrides — particularly module overrides — Joomla picks them up automatically as soon as the file is in the correct location. For layout overrides that introduce an alternative layout (a second layout option rather than a direct replacement of the default), you need to activate it explicitly. Navigate to the module or component in the administrator, open its settings, and look for the Layout field. Your new override will appear as a selectable option. Choose it and save.

Verifying That the Override is Working Properly

After saving, visit the relevant page on the front end and confirm that your changes are rendering correctly. Use your browser's developer tools to inspect the markup and verify that your custom classes, structural changes, or new elements are present. If you are not seeing your changes, check the file path of your override, clear Joomla's cache under System → Clear Cache, and confirm that the correct template is assigned to the page you are viewing.

Troubleshooting Common Issues

Debugging Layout Override Errors in Joomla

The most frequent causes of override failures are an incorrect directory path, a misnamed file, or a PHP syntax error introduced during editing. Enable Joomla's debug mode via System → Global Configuration → System and set both Debug System and Debug Language to Yes. This surfaces PHP errors and Joomla-level warnings directly in the browser output, making it much faster to locate the problem. Joomla 6's administrator also includes an override manager that highlights files where the override has diverged significantly from the current upstream version — a useful early warning system after updates.

Reverting Changes: How to Roll Back if Something Goes Wrong

Rolling back is straightforward: rename or delete the override file, and Joomla falls back to the original automatically. There is no cache to flush or configuration to update. If you are using version control, a single git revert or file restore from your repository history is all that is needed. This is one of the strongest arguments for keeping your template directory under source control from the start of a project.

Fixing Compatibility Issues with Joomla Extensions

Third-party extensions occasionally introduce structural changes to their view files in updates, which can cause your override to render incorrectly or throw errors. After updating any extension whose output you have overridden, check the Joomla override manager to see whether the upstream file has changed. If it has, review the diff, incorporate any necessary structural changes into your override, and test again. Making this part of your post-update checklist prevents subtle layout regressions from going unnoticed.

Best Practices for Maintaining Layout Overrides

Keeping Overrides Updated with Joomla Core and Extension Updates

Joomla 6's administrator flags override files that are out of sync with their originals — a feature introduced in earlier versions and refined significantly since. After any Joomla core update or extension update, review the override status screen and address any flagged files promptly. An override that was written against an older version of a layout file may silently omit new functionality or security improvements introduced upstream.

Documenting Your Layout Overrides for Future Use

On any project beyond a simple personal site, documentation is not optional. Record which files have been overridden, what changes were made, and the business or design reason behind each change. A brief comment block at the top of each override file is the minimum; for larger projects, a separate document or wiki entry listing all active overrides, their purpose, and their last-reviewed date is worth the investment. This documentation pays dividends when handing a project to another developer or returning to it after months away.

When to Use Layout Overrides vs. Custom Templates

Layout overrides are the right tool when you need to adjust the output of specific components or modules within an otherwise standard template. If the scope of changes is so broad that you are overriding the majority of a template's files, or if you are building a completely bespoke design from the ground up, creating a custom child template — or a full custom template — is the more appropriate path. Joomla 6 supports child templates natively, which offers a middle ground: inherit the parent template's structure and assets, then override only what needs to differ. For targeted, maintainable customisations, however, layout overrides remain the cleanest solution available.

Conclusion and Next Steps

Expanding Your Joomla Skills with More Advanced Layout Techniques

With a solid grasp of layout overrides, the next step is exploring Joomla's JLayout system more deeply. JLayout allows you to create reusable layout partials that can be called from multiple places across your site, reducing duplication and keeping your override files focused. You can also override the JLayout files themselves, giving you control over shared UI elements that appear across many different components and modules. Joomla 6's expanded use of JLayout throughout the core makes this a particularly productive area to explore.

Leveraging Layout Overrides for Future Projects

The discipline of working with layout overrides — understanding file paths, respecting the boundary between presentation and logic, testing systematically, and documenting changes — translates directly into faster, more reliable Joomla development across every project you take on. Clients benefit from sites that survive updates without breaking. Developers benefit from a codebase that is easier to hand over, maintain, and extend. Layout overrides, used well, are one of the features that make Joomla a genuinely professional platform in 2026.