Joomla Template Overrides — Customizing Layouts Without Hacking Core

In this tutorial, you'll learn how Joomla template overrides let you customize component layouts, module layouts, module chrome, and pagination — all without modifying core files, keeping your changes safe during updates.

What You'll Learn

• What template overrides are and why they matter
• How the override system works — Joomla checks the template before core files
• How to create a component override via the admin interface
• Which com_content files you can override: article/default.php, category/blog.php, and more
• How to create module overrides for mod_articles_latest, mod_menu, mod_search
• Where override files live: templates/cassiopeia/html/com_content/article/default.php
• How module chrome overrides work
• Pagination overrides in layout/joomla/pagination/
• The file signature requirements: same function calls and _JEXEC check
• When overrides survive updates and when they do not
• Best practices for managing overrides

Why It Matters

Every Joomla site eventually needs custom output that the default layouts do not provide. Beginners often edit core template or component files directly. When Joomla updates, those edits are overwritten and lost. Template overrides solve this problem by letting you copy a layout file to your template folder, customize it, and keep those customizations forever — even as Joomla versions change.

Real-World Use

A real estate agency uses Joomla for its property listings. The default article layout shows the title, then the intro text, then the full text. The agency needs the property price, agent name, and gallery to appear before the description. They create a template override for com_content's article/default.php, rearrange the output, and the property pages display exactly as they want. When Joomla 5.1 is released, the override remains intact.

Learning Path

flowchart LR
  A["Template Styles"] --> B["Template Overrides
You are here"]:::current
  B --> C["Child Templates"]
  C --> D["CSS & User.css"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

What Are Template Overrides?

A template override is a copy of a layout file from a component, module, or plugin that you place in your template's html folder. When Joomla renders a page, it checks:

1. Does the active template have an override for this layout? If yes, use that.
2. If not, use the default layout from the component or module.

This lookup order means you can replace any layout file in the system by placing a modified copy in your template.

flowchart TD
  A["Page Request
for Article"] --> B{"Override exists in
active template?"}
  B -->|Yes| C["Use template/html/
com_content/article/default.php"]
  B -->|No| D["Use components/
com_content/views/article/tmpl/default.php"]
  C --> E["Render with customizations"]
  D --> E

How to Create a Component Override

Joomla provides a built-in tool for creating overrides:

1. Go to Extensions > Templates > Templates
2. Click the Cassiopeia template name
3. Open the Create Overrides tab
4. You see a list of all installed components and modules
5. Click com_content (or any component) to create overrides for all its views

Joomla copies the default layout files from the component to your template's html folder. You can then edit them in the template editor or via FTP.

# Steps to create an override
# Extensions > Templates > Templates > Cassiopeia
# Click "Create Overrides" tab
# Find com_content in the list
# Click com_content
# All view layouts are now copied to your template
# Edit them under the template's html/com_content/ folder

What Gets Overridden

When you create an override for com_content, Joomla copies these files:

templates/cassiopeia/html/com_content/
├── article/
│   ├── default.php        # Single article view
│   └── icons.php          # Print/email/edit icons
├── category/
│   ├── blog.php           # Category blog layout
│   ├── blog_item.php      # Individual item in blog
│   ├── blog_links.php     # Links section at bottom of blog
│   └── list.php           # Category list layout
├── featured/
│   └── default.php        # Featured articles view
├── frontpage/
│   └── default.php        # Legacy frontpage (Joomla 3)
└── archive/
    └── default.php        # Archived articles list

Editing an Override

Once the override files exist, you edit them just like any template file. Here is an example of the article default.php override:

<?php
defined('_JEXEC') or die;

use Joomla\CMS\Factory;
use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;
use Joomla\CMS\Router\Route;

$app = Factory::getApplication();
$user = $app->getIdentity();
$params = $this->params;
$article = $this->item;
?>

<div class="com-content-article item-page<?php echo $this->pageclass_sfx; ?>">
  <meta itemprop="inLanguage" content="<?php echo $this->item->language; ?>">

  <?php if ($params->get('show_page_heading')) : ?>
    <h1><?php echo $this->escape($params->get('page_heading')); ?></h1>
  <?php endif; ?>

  <div class="page-header">
    <h2 itemprop="headline">
      <?php echo $this->escape($article->title); ?>
    </h2>
  </div>

  <div class="article-info">
    <?php if ($params->get('show_category')) : ?>
      <span class="category-name">
        <?php echo Text::_('COM_CONTENT_CATEGORY'); ?>:
        <a href="<?php echo Route::_(ContentHelperRoute::getCategoryRoute($article->catid)); ?>">
          <?php echo $this->escape($article->category_title); ?>
        </a>
      </span>
    <?php endif; ?>
  </div>

  <div itemprop="articleBody" class="com-content-article__body">
    <?php echo $article->text; ?>
  </div>
</div>

The file must start with defined('_JEXEC') or die; — this is a security check that prevents direct access to the file. Every Joomla layout file needs this line.

Module Overrides

Module overrides work the same way as component overrides. You copy the module's tmpl files to your template's html folder.

Create a module override:

1. Extensions > Templates > Templates > Cassiopeia
2. Create Overrides tab
3. Scroll to the Modules section
4. Click mod_articles_latest, mod_menu, or mod_search

# After creating mod_menu override:
templates/cassiopeia/html/mod_menu/
├── default.php          # Default menu layout
├── default_submenu.php  # Submenu items layout
└── default_separator.php # Separator items layout

Module Override Example

Here is part of a mod_articles_latest override showing how to customize the list of latest articles:

<?php
defined('_JEXEC') or die;

use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;
use Joomla\CMS\Router\Route;

$items = $list;
?>

<ul class="mod-articleslatest latestnews mod-list">
  <?php foreach ($items as $item) : ?>
    <li itemscope itemtype="https://schema.org/Article">
      <a href="<?php echo $item->link; ?>" itemprop="url">
        <span itemprop="name">
          <?php echo $item->title; ?>
        </span>
      </a>
      <small class="published">
        <?php echo HTMLHelper::_('date', $item->publish_up, Text::_('DATE_FORMAT_LC3')); ?>
      </small>
    </li>
  <?php endforeach; ?>
</ul>

Module Chrome Overrides

Module chrome refers to the HTML wrapper that surrounds every module — the div container, the heading, and the module class suffixes. You can override module chrome by copying files from modules/mod_menu/tmpl/ or creating custom chrome in your template.

Standard module chrome in Joomla:

// Default module chrome in Joomla
// templates/system/html/modules.php
<?php
defined('_JEXEC') or die;

function modChrome_default($module, &$params, &$attribs)
{
  $moduleTag     = $params->get('module_tag', 'div');
  $headerTag     = htmlspecialchars($params->get('header_tag', 'h3'));
  $bootstrapSize = (int) $params->get('bootstrap_size', 0);
  $moduleClass   = $bootstrapSize ? ' span' . $bootstrapSize : '';

  if ($module->content) :
    echo '<' . $moduleTag . ' class="moduletable ' . htmlspecialchars($params->get('moduleclass_sfx')) . $moduleClass . '">';
    if ($module->showtitle) :
      echo '<' . $headerTag . ' class="module-title">' . $module->title . '</' . $headerTag . '>';
    endif;
    echo $module->content;
    echo '</' . $moduleTag . '>';
  endif;
}

To create custom module chrome, copy the modules.php file to your template:

# Location for custom module chrome
templates/cassiopeia/html/modules.php

Using Custom Module Chrome

Once you create a custom chrome function in your template's modules.php, you can select it in the module editor under Advanced > Module Style.

// Custom module chrome in templates/cassiopeia/html/modules.php
<?php
defined('_JEXEC') or die;

function modChrome_card($module, &$params, &$attribs)
{
  if ($module->content) :
    echo '<div class="card mb-3">';
    if ($module->showtitle) :
      echo '<div class="card-header">' . $module->title . '</div>';
    endif;
    echo '<div class="card-body">';
    echo $module->content;
    echo '</div>';
    echo '</div>';
  endif;
}

Pagination Overrides

Pagination layout can also be overridden. The pagination files are in layouts/joomla/pagination/:

# Default pagination layout
layouts/joomla/pagination/
├── links.php     # Page number links
└── list.php      # Previous/Next list

# Override location
templates/cassiopeia/html/layouts/joomla/pagination/
├── links.php
└── list.php

To create a pagination override, copy the file from layouts/ to your template's html/layouts/ folder and edit it.

<?php
defined('_JEXEC') or die;

// Override pagination links.php to add Bootstrap styling
$list = $displayData['list'];
$pages = $list['pages'];
?>

<nav aria-label="Pagination">
  <ul class="pagination justify-content-center">
    <?php if ($list['previous']['active']) : ?>
      <li class="page-item">
        <a class="page-link" href="<?php echo $list['previous']['link']; ?>" aria-label="Previous">
          <span aria-hidden="true">&laquo;</span>
        </a>
      </li>
    <?php endif; ?>

    <?php foreach ($pages as $page) : ?>
      <li class="page-item<?php echo $page['active'] ? ' active' : ''; ?>">
        <a class="page-link" href="<?php echo $page['link']; ?>">
          <?php echo $page['text']; ?>
        </a>
      </li>
    <?php endforeach; ?>

    <?php if ($list['next']['active']) : ?>
      <li class="page-item">
        <a class="page-link" href="<?php echo $list['next']['link']; ?>" aria-label="Next">
          <span aria-hidden="true">&raquo;</span>
        </a>
      </li>
    <?php endif; ?>
  </ul>
</nav>

Override File Requirements

Every override file must:

1. Start with the _JEXEC check: defined('_JEXEC') or die; prevents direct access
2. Use the same variable names: The override receives the same data as the original
3. Maintain the same function calls: Use the same Joomla APIs and helpers
4. Keep the same PHP structure: The opening and closing PHP tags must match

If you violate these rules, the override can break completely or create security vulnerabilities.

When Overrides Survive Updates

Template overrides survive when:

• You update Joomla core (e.g., 5.0.1 to 5.0.2)
• You update a component or module
• You change the active template

Overrides are lost when:

• You uninstall the template
• You manually delete the override files
• The component changes its view structure (rare, but happens in major versions)

When upgrading from Joomla 4 to Joomla 5, some components changed their view structure. Overrides for those components needed updating. Check the Joomla documentation for your override files before major version upgrades.

Override Best Practices

Copy Only What You Edit

When you create an override, Joomla copies all view files. If you only need to modify one file, delete the others. This keeps your template clean and makes future debugging easier.

# After creating com_content override, you only need article/default.php
# Delete the other override files you are not using:
rm templates/cassiopeia/html/com_content/article/icons.php
rm templates/cassiopeia/html/com_content/category/blog.php
# Keep only what you customize

Document Your Changes

Add comments (sparingly) to explain what you changed and why:

// Changed: Added category image above article title
// Date: 2026-06-27
// Reason: Client wants visual category indicators
if ($params->get('show_category')) :
  $images = json_decode($article->category_images);
  if ($images->image_intro) :
    echo '<img src="' . htmlspecialchars($images->image_intro) . '" alt="">';
  endif;
endif;

Check Overrides After Major Updates

When a new Joomla major version is released, compare your override against the new default layout. The component may have added new features or changed variables. Diff your override against the new file to see what changed.

Use Child Templates for Complex Customizations

If you need many overrides, consider creating a child template. Child templates keep all your changes in one place and let you switch between different override sets by changing the active template.

Common Mistakes

1. Editing core files instead of creating overrides: Beginners edit files in components/com_content/ directly. When Joomla updates, these files are replaced and the changes are lost. Always use the Create Overrides tool.

2. Missing the _JEXEC check: Override files without defined('_JEXEC') or die; are a security vulnerability. Anyone who knows the file path can execute the PHP file directly, potentially exposing sensitive data.

3. Overriding too many files: Creating overrides for every view when you only need to change one small thing. This creates unnecessary maintenance. Only override the specific files you need to change.

4. Not updating overrides after Joomla version upgrades: An override from Joomla 4 may not work correctly in Joomla 5 because the component view changed. Test all overrides after upgrading.

5. Forgetting to check template overrides when changing templates: Overrides are template-specific. If you switch from Cassiopeia to a different template, your overrides do not carry over. You need to recreate them for the new template.

Practice Questions

1. Where does Joomla look first for a layout file — the template or the component? Answer: Joomla checks the active template's html folder first. If an override exists there, it uses that. If not, it falls back to the component's default layout file.

2. How do you create a template override using the admin interface? Answer: Go to Extensions > Templates > Templates, click the active template (Cassiopeia), open the Create Overrides tab, find the component or module you want to override, and click it. Joomla copies all view files to the template's html folder.

3. What happens to template overrides when Joomla is updated? Answer: Template overrides survive Joomla core updates because they are stored in the template folder, not in the core files. However, during major version upgrades, you may need to update overrides if the component view structure changed.

4. Challenge: Create a custom module chrome function that wraps modules in a Bootstrap card component. Then apply it to a specific module on your site. The card should have a header (module title), body (module content), and optional footer. Use your custom chrome in a sidebar position for a more modern look.

FAQ

Mini Project

Your task: Customize the article layout for a photography portfolio site.

1. Create a com_content template override for Cassiopeia.
2. Edit the article/default.php to show:
   • A large featured image at the top (before the title)
   • The article category as a badge
   • The article title
   • A byline with author name and publish date
   • The full article text
   • Tags at the bottom as linked badges
3. Create a pagination override that uses Bootstrap 5 pagination classes.
4. Create a module chrome override that renders modules in a styled sidebar card.
5. Assign a custom HTML module to the sidebar with the new chrome.
6. Verify all changes display correctly on the frontend.

This exercise mirrors a real client request — changing article layout is one of the most common Joomla customization tasks.

What's Next

Now that you can customize layouts through overrides, you are ready to learn about child templates for more complex customization:

Continue to Lesson 18: Creating a Child Template — Learn how to build a child template that inherits from Cassiopeia and adds custom module positions and styling.

Related lessons:

• Joomla Template Basics — Understand the template folder structure
• Joomla CSS and User.css — Add custom styles to your overrides