On this page

# Topics

Configuring Joomla Breadcrumbs

04 July 2026

Breadcrumbs look like the simplest thing on a Joomla page: a small trail of links near the top that says "Home / News / Joomla 6 Released". Yet that little trail is built from the menu tree, the active menu item, and sometimes the component you are viewing. Once you see how Joomla assembles it, you can fix broken trails, style them properly, and turn them into real SEO value.

This article explains how Joomla breadcrumbs really work. It covers the basics for website owners and editors, the practical setup for administrators, and the technical details for developers. You will learn what the Pathway is, how the Breadcrumbs module turns it into a visible trail, how components add their own steps, how the trail becomes structured data for search engines, and how to avoid the common mistakes.

Breadcrumbs are not a setting you type in. They are a live picture of where the current page sits in your menu tree.

The goal is simple: help you understand breadcrumbs well enough to use them with confidence.

1. The Basics

A breadcrumb trail is a row of links that shows the path from the home page down to the page a visitor is viewing. It usually looks like this:

Home → Products → Laptops → ThinkPad X1

Each step except the last is a link. The last step is the current page, so it is normally plain text. The name comes from the fairy tale: a trail of crumbs that shows the way back.

1.2 Why Breadcrumbs Matter

Breadcrumbs do three useful jobs at once:

Orientation: visitors see where they are in the site structure.
Navigation: visitors can jump back up to any parent level in one click.
SEO: search engines read the trail, show it in results, and understand your site hierarchy.

1.3 Where Do Breadcrumbs Come From in Joomla?

This is the part newcomers miss. In Joomla you do not write the trail by hand. Joomla keeps an internal object called the Pathway. The Pathway is filled automatically:

The active menu item and its parent menu items form the base of the trail.
The component you are viewing (for example an article) can add more steps, such as the category and the article title.

A separate module, mod_breadcrumbs, reads the Pathway and renders it as a visible trail. No module means no visible breadcrumbs, even though the Pathway still exists.

The Pathway is the data. The Breadcrumbs module is the display.

A rendered trail in Joomla 6 has these parts:

Part	What it is
"You are here:" label	An optional prefix in front of the trail.
Home crumb	An optional first link to the site home page.
Middle crumbs	One link per parent menu item or category, each clickable.
Last crumb	The current page, shown as plain text (optional).

2. Showing Breadcrumbs on Your Site

2.1 Publish the Breadcrumbs Module

Breadcrumbs appear only when you publish the Breadcrumbs module. To add it, go to:

System → Site Modules → New → Breadcrumbs

Then set three things:

Title: for example "Breadcrumbs". You can hide the title on the frontend.
Position: choose a template position near the top of the content, such as breadcrumbs in the default Cassiopeia template.
Status: set it to Published.

2.2 Choose Where It Appears

Like every module, the Breadcrumbs module has a Menu Assignment tab. You decide where the trail shows:

On all pages (the usual choice).
On all pages except the home page (very common, because a trail on the home page is pointless).
Only on selected pages.

A clean default is "On all pages" combined with hiding the Home crumb, or "All pages except Home".

2.3 Confirm the Template Position Exists

If you publish the module but see nothing, the chosen position may not exist in your template. You can preview positions by enabling Preview Module Positions in the Templates options, then append ?tp=1 to a frontend URL (spoiler: you can type anything except 0, ?tp=peter also works!). The Cassiopeia template ships a dedicated breadcrumbs position for exactly this purpose.

3. Module Options Explained

The Breadcrumbs module has a small but important set of options. Each one maps directly to a parameter in the module configuration.

3.1 Basic Options

Option	Parameter	What it does
"You are here"	`showHere`	Shows the "You are here:" label before the trail. When off, Joomla shows a small location icon instead.
Home	`showHome`	Adds the Home link as the first crumb.
Text for Home Entry	`homeText`	Overrides the word "Home". Leave it empty to use the language default.
Last	`showLast`	Shows the current page as the final crumb. Turn it off to end the trail at the parent.

3.2 Advanced Options

Option	Parameter	What it does
Layout	`layout`	Selects a layout file, including one from a template override.
Module Class Suffix	`moduleclass_sfx`	Adds a CSS class to the module's outer wrapper, the module chrome. The layout itself does not output it. In Cassiopeia, the `breadcrumbs` position uses the style `none`, so the class only appears if you also choose a Module Style on the Advanced tab.
Caching	`cache`	Use Global or No caching. The default is No caching.
Cache Time	`cache_time`	How long, in seconds, to keep the cached output.

There is also a hidden parameter, cachemode, fixed to itemid. When caching is on, Joomla stores one version of the trail per menu item, not per URL. That can show the wrong trail for articles that share a menu item, so it is usually best to keep caching off. See section 13 for the details.

3.3 The "Show Last" Trick

Many designers turn showLast off. The current page already has an <h1> heading, so repeating its title in the trail can feel redundant. Turning it off ends the trail at the last parent. It is a matter of taste, but it keeps the trail shorter.

4. How the Trail is Built: the Pathway

4.1 The Pathway Object

Behind every frontend page, Joomla keeps a Pathway object. It is a simple list. Each entry has two fields:

name   -- the visible label of the crumb
link   -- the internal URL the crumb points to, e.g. index.php?option=...&Itemid=...
          (empty for Headings, Separators and crumbs added without a link)

The link is stored as a non-SEF internal URL. The Breadcrumbs module turns it into a SEF URL when it renders the trail.

The last crumb is always shown as plain text, whether or not it has a link. When the current page is a menu item, its crumb still has a link in the Pathway: only the layout leaves it out. When a component adds the current page itself, such as an article title, the link is usually empty.

The class lives in Joomla\CMS\Pathway\Pathway, and the frontend uses the subclass Joomla\CMS\Pathway\SitePathway. You reach the active instance from the application:

$pathway = $app->getPathway();

When a page loads, Joomla looks at the active menu item. Every menu item knows its ancestors through a tree property: the chain of parent items from the top down to the item itself. SitePathway walks that tree and adds one crumb per menu item in it, including the active item itself. Each crumb uses the menu item's title as its label.

One important detail: if the active item is the home page, Joomla adds nothing. The trail body stays empty, and only the optional Home crumb from the module is left.

On other pages, the home item normally does not appear in the trail body, because it is usually a top-level item and not a parent of other items. If you do place menu items under the home item, the home item becomes part of their tree and shows up as a crumb. The default layout then removes it when it directly follows the Home crumb, so the trail does not show "Home → Home".

Not every menu item becomes a clickable crumb. SitePathway treats some types differently:

Menu item type	Crumb behaviour
Separator	Shown as a label, no link.
Heading	Shown as a label, no link.
URL	Linked. Joomla adds the `Itemid` for internal links.
Alias	Linked to the aliased item using its `aliasoptions` parameter.
Component	Linked, with the `Itemid` appended.

This is why a Heading used as a dropdown parent shows up in the trail as plain text: it has no real page to link to.

5. How Components Extend the Trail

The menu tree gives the base trail, but it stops at the menu item. A Single Article menu item, for example, does not know which article you opened from a category blog. So components add their own crumbs at runtime.

5.2 Articles Add Category and Title Crumbs

When you open an article that is not directly linked to its own menu item, the Articles component (com_content) builds the missing steps. It starts from the article and walks up the category tree, adding each category as a crumb, until it reaches the category of the active menu item. In code, the Article view does this:

$pathway = $app->getPathway();

$path     = [['title' => $this->item->title, 'link' => '']];
$category = Categories::getInstance('Content')->get($this->item->catid);

while ($category !== null && $category->id != $id && $category->id !== 'root') {
    $path[]   = ['title' => $category->title, 'link' => RouteHelper::getCategoryRoute($category->id, $category->language)];
    $category = $category->getParent();
}

$path = array_reverse($path);

foreach ($path as $item) {
    $pathway->addItem($item['title'], $item['link']);
}

Here, $id is the category of the active menu item, but only if that menu item is a Category (Blog or List) or a Categories menu item. For any other menu item type, $id is 0, and Joomla adds the full category path of the article, up to the top level.

Example: a Category Blog menu item "News" shows the category News. An article in News → Products → Laptops then gets this trail, even though only "News" is a real menu item:

Home → News → Products → Laptops → ThinkPad X1

The last crumb is the article title. It is added without a link, because it is the current page.

5.3 Why This Matters for Your Content

Because components fill the gap from the menu item down to the content, the quality of your trail depends on two things:

A clean category tree, since article breadcrumbs follow the category parents.
A correct Itemid, since the starting menu item decides where the component trail begins.

If Joomla guesses the wrong Itemid, the trail can start in the wrong branch. This is the single most common cause of "weird breadcrumbs".

6. Breadcrumbs and the Itemid

6.1 The Itemid Sets the Starting Point

Every frontend page is tied to a menu item through the Itemid parameter. The Pathway uses the active menu item to build its base, so the Itemid directly decides:

Which menu items appear as crumbs: the active menu item and its parents.
Where the component trail attaches.
Whether the Pathway stays empty. On the home menu item, Joomla adds no menu crumbs at all. The Home crumb itself still appears if the Home option (showHome) is on, because the module adds it, not the Pathway.

6.2 What Goes Wrong Without a Clear Itemid

If a link to an article has no Itemid, Joomla's router guesses one. A wrong guess produces:

A trail that starts in the wrong menu branch.
Missing or doubled crumbs.
A different trail for the same article reached from two places.

6.3 How to Inspect It

Before SEF rewriting hides it, the Itemid is the last number in the query string:

index.php?option=com_content&view=article&id=42&Itemid=123

When a breadcrumb trail looks wrong, check the Itemid first. The fix is usually to link to the content through the right menu item, or to create a dedicated menu item for that page.

7.1 The Request Flow, Step by Step

A breadcrumb trail is the last step of a longer process. When a visitor opens a page, Joomla runs roughly these steps:

The SiteRouter receives the request URL, for example /news/products/laptops.
The router parses the URL and resolves the Itemid, which sets the active menu item.
The first time anything asks for the Pathway, usually the component, Joomla creates SitePathway. It builds the base trail by walking the active menu item's tree: its parents plus the item itself. On the home menu item it adds nothing.
The matching component runs. If needed, it calls addItem() to append deeper crumbs, such as the category chain and the article title.
The template renders its module positions. mod_breadcrumbs asks its helper for the finished list and, if enabled, prepends the Home crumb.
The layout renders the trail as an ordered list and adds the schema.org structured data as JSON-LD to the page.

This is why breadcrumbs depend so heavily on routing and menu configuration. The module itself does almost nothing: by the time it runs, the trail is already decided.

7.2 The Sequence at a Glance

The same flow as a diagram, from the browser request down to the HTML:

Browser request
      ↓
SiteRouter          resolves the Itemid and the active menu item
      ↓
SitePathway         adds the active menu item and its parents as crumbs
                    (nothing on the home menu item)
      ↓
Component           addItem() for category and article crumbs
      ↓
Plugins             onAfterDispatch: optional extra crumbs
      ↓
mod_breadcrumbs     reads the Pathway, prepends the Home crumb
      ↓
Layout (default)    renders the list and the schema.org JSON-LD
      ↓
HTML in the page

7.3 Why the Order Matters

Each stage can only work with what the earlier stages produced. A wrong Itemid in step 2 sends the rest of the chain down the wrong branch. A component that forgets to call addItem() in step 4 leaves the deep crumbs missing. When you troubleshoot, start at the top of this list and work down: router first, module last.

8. Under the Hood (Developer View)

8.1 The Pathway API

The Pathway exposes a small, stable API. You can read or change the trail from a plugin or a custom component:

use Joomla\CMS\Factory;

$app     = Factory::getApplication();
$pathway = $app->getPathway();

// Read
$items = $pathway->getPathway();        // array of objects with name + link
$names = $pathway->getPathwayNames();    // array of just the names

// Write
$pathway->addItem('Downloads', 'index.php?option=com_downloads&view=list&Itemid=55');
$pathway->setItemName(2, 'Renamed crumb');
$pathway->setPathway($newArrayOfItems); // replace the whole trail

Each item is a plain stdClass with a name and a link. An empty link means the crumb renders as text, not a hyperlink.

8.2 Where SitePathway Builds the Base

The frontend subclass Joomla\CMS\Pathway\SitePathway builds the base trail in its constructor. It reads the active menu item, skips the home item, and walks the tree property, choosing a link per item type (separator, heading, url, alias, or component). Everything after that is added by components through addItem().

8.3 A Plugin Example

A System plugin can adjust the trail after the component has added its own crumbs. Use the onAfterDispatch event for that: it runs after the component and before the template renders the modules. In Joomla 6, a plugin subscribes to events through SubscriberInterface:

use Joomla\CMS\Event\Application\AfterDispatchEvent;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;

final class SpecialOffer extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onAfterDispatch' => 'onAfterDispatch'];
    }

    public function onAfterDispatch(AfterDispatchEvent $event): void
    {
        $app = $event->getApplication();

        if (!$app->isClient('site')) {
            return;
        }

        $app->getPathway()->addItem('Special Offer', '');
    }
}

Be careful with the timing. On onAfterRoute the component has not run yet, so a crumb you add there ends up before the component's crumbs, in the middle of the trail. To insert a crumb at a specific place, read the list with getPathway(), change the array, and write it back with setPathway().

This is how third-party extensions insert their own crumbs without touching core files.

8.4 There is No Breadcrumbs Table

The trail is never stored. It is rebuilt on every request from the live menu tree and the current content. Breadcrumbs therefore have no dedicated database table. Instead, the module leans on a handful of core tables. The next subsections list the ones that matter.

This is the most important table, because it holds the menu tree that forms the base of every trail. The relevant columns are:

id             -- menu item id, used as the Itemid
title          -- the menu item title, used as the crumb label
parent_id      -- the parent menu item
level          -- depth in the tree
lft, rgt       -- Nested Set Model boundaries
path           -- the alias path (parent/child/grandchild)
alias          -- the URL segment
type           -- component | url | alias | separator | heading
component_id   -- the linked component
link           -- the underlying index.php?option=... query
home           -- marks the default (home) menu item, per language
published      -- only published items (within their publish dates) are loaded
access, language
               -- not checked when the trail is built (see below)

Joomla does not query this table for each crumb. On every frontend request it loads all published site menu items in one query, sorted by lft. It caches that list when caching is enabled. Then it builds each item's tree (the chain of parent ids down to the item itself) in PHP, from parent_id.

The lft and rgt columns implement the Nested Set Model. Sorting by lft guarantees that every parent comes before its children, so each item can simply copy its parent's tree and add its own id. The breadcrumb trail then only has to walk that ready-made tree, which is why building it is so fast.

The menu list is not filtered by access level, and SitePathway uses every item in the tree as it is. So if a parent menu item has the access level Registered and its child is Public, a guest on the child page still sees the parent as a linked crumb. That link leads to a page the guest cannot open. Give a parent menu item an access level that is at least as open as the access levels of its children.

The Breadcrumbs module itself is a normal module, so its configuration lives in #__modules:

Column	What it holds
`title`	The module title.
`position`	The template position it renders in.
`params`	A JSON blob with the options (`showHome`, `showLast`, and so on).
`published`, `access`, `language`	Status, access level, and language.

The companion table #__modules_menu maps each module to the menu items it appears on. For breadcrumbs, this is what your Menu Assignment choice writes:

moduleid   -- which module
menuid     -- which menu item (Itemid)
             positive = "show on this item"
             negative = "show on all except these items"
             0        = "all pages"

So "All pages except Home" is stored here as a negative row for the home menu item.

8.7 Supporting Tables

#__extensions: registers mod_breadcrumbs as an installed extension. When it loads modules, Joomla only uses modules whose extension is enabled here. The module's settings are not stored here: they live in the params column of #__modules, and the defaults come from the module's XML file.
#__viewlevels: defines the access levels (Public, Registered, and so on). The access column in #__modules points to a level here. Joomla only loads the Breadcrumbs module for visitors who have that access level.
#__assets: holds the ACL permission rules, such as who may edit, delete or change the state of the module in the back-end. These rules do not decide who sees the module on the frontend.

None of these store the trail itself. Together they describe the menu structure, the module, and who may see it, and Joomla rebuilds the breadcrumbs from them on every request.

9. The Module Helper and Rendering

9.1 From Pathway to HTML

The Breadcrumbs module turns the Pathway into HTML in three steps:

The module Dispatcher asks the helper for the list of crumbs.
The BreadcrumbsHelper reads the Pathway and, if showHome is on, prepends the Home crumb.
The layout file (tmpl/default.php) renders the list as an ordered list of links.

9.2 The Modern Helper Call

In Joomla 6 the helper is a normal service, not a static call. The modern way to get the crumbs is:

$crumbs = Factory::getApplication()
    ->bootModule('mod_breadcrumbs', 'site')
    ->getHelper('BreadcrumbsHelper')
    ->getBreadcrumbs($params, Factory::getApplication());

The old static methods BreadcrumbsHelper::getList() and getHome() still exist, but they are deprecated since 4.4.0 and will be removed in Joomla 7.0. New code should use the instance methods getBreadcrumbs() and getHomeItem().

9.3 The Home Crumb Logic

The helper method getHomeItem() builds the Home crumb from the default menu item. On a multilingual site, it uses the default menu item of the current language:

if (Multilanguage::isEnabled()) {
    $home = $menu->getDefault($app->getLanguage()->getTag());
} else {
    $home = $menu->getDefault();
}

$item->name = htmlspecialchars($params->get('homeText', $app->getLanguage()->_('MOD_BREADCRUMBS_HOME')), ENT_COMPAT, 'UTF-8');
$item->link = $home->link . '&Itemid=' . $home->id;

If homeText is empty, the label comes from the language string MOD_BREADCRUMBS_HOME, so "Home" is translated automatically.

If showHome is on, the helper puts this item at the start of the list. If showHome is off, the module's Dispatcher still calls getHomeItem() and passes the result to the layout as a fallback $homeCrumb. The layout uses it only for the structured data (see the SEO section). That way the trail can hide the Home link visually while keeping it in the machine-readable data.

10. Template Overrides and Styling

10.1 The Default Markup

The Joomla 6 default layout outputs semantic, accessible markup based on Bootstrap classes. With the default settings ("You are here" on, Home on, Last on), a short trail looks like this:

<nav class="mod-breadcrumbs__wrapper" aria-label="Breadcrumbs">
  <ol class="mod-breadcrumbs breadcrumb px-3 py-2">
    <li class="mod-breadcrumbs__here float-start">
      You are here: &#160;
    </li>
    <li class="mod-breadcrumbs__item breadcrumb-item">
      <a href="/" class="pathway"><span>Home</span></a>
    </li>
    <li class="mod-breadcrumbs__item breadcrumb-item active">
      <span>Current Page</span>
    </li>
  </ol>
</nav>

When "You are here" is off, the first <li> gets the class mod-breadcrumbs__divider instead, and contains a location icon in place of the text.

The <nav> wrapper with an aria-label tells screen readers this is a navigation landmark. The aria-label is the module title, so "Breadcrumbs" above is just the title of this example module. Give the module a clear title, even when you hide it on the frontend.

The last crumb gets the active class. If you want an even stronger accessibility signal, an override can add aria-current="page" to the last crumb.

10.2 Creating an Override

To change the markup, never edit the module. Create a template override instead. For the Cassiopeia template:

templates/cassiopeia/html/mod_breadcrumbs/default.php

Copy the original modules/mod_breadcrumbs/tmpl/default.php into that path, then edit your copy. Joomla loads the override automatically. The Templates manager has a built-in editor that creates this override for you:

System → Site Templates → [your template] → Create Overrides → mod_breadcrumbs

10.3 Styling Without an Override

For simple visual changes you do not need an override at all. The default layout already outputs its own classes, so you can target them directly in your template CSS. In Cassiopeia, put your rules in user.css. You can create that file in the template manager, and Cassiopeia loads it automatically.

.mod-breadcrumbs { font-size: 0.9rem; }
.mod-breadcrumbs__item.active span { color: #666; }
.mod-breadcrumbs { --breadcrumb-divider: "→"; }

Cassiopeia draws the divider between crumbs from the CSS variable --breadcrumb-divider, with / as the default. Setting the variable is enough: you do not need to override the ::before rule.

You do not need the Module Class Suffix for this. The layout does not output it, and in Cassiopeia's breadcrumbs position the module has no wrapper, so the suffix never appears. Use it only when you need different styling for a second Breadcrumbs module, and then also choose a Module Style such as html5 on the module's Advanced tab, so the suffix is printed on a wrapper element.

11. Structured Data and SEO

11.1 Breadcrumbs Help Search Engines

Breadcrumbs are one of the cheapest SEO wins in Joomla. They give search engines a clear map of your site hierarchy, and Google often shows the trail instead of the raw URL in search results.

11.2 Built-in Structured Data

The Joomla 6 Breadcrumbs module outputs schema.org BreadcrumbList structured data automatically, with no configuration needed. The layout adds it as a JSON-LD script through the Web Asset Manager, which Cassiopeia outputs in the page <head>. For an article opened from a "News" menu item, it looks like this:

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "@id": "https://example.test/#/schema/BreadcrumbList/17",
  "itemListElement": [
    { "@type": "ListItem", "position": 1,
      "item": { "@id": "https://example.test/", "name": "Home" } },
    { "@type": "ListItem", "position": 2,
      "item": { "@id": "https://example.test/news", "name": "News" } },
    { "@type": "ListItem", "position": 3,
      "item": { "name": "Joomla 6 Released" } }
  ]
}

The @id of the list contains the module id (here 17). The System - Schema.org plugin uses it to link the breadcrumbs to the WebPage in its own schema graph.

A few rules decide which crumbs end up in the data:

Crumbs with a link get an @id with the full URL.
Crumbs without a link, such as Headings and Separators, are skipped. The positions keep counting without gaps.
The last crumb without a link is still added, with only a name. Google accepts a URL-less entry only for the current page. Here the article title was added by com_content without a link. If the current page is a menu item, its crumb has a link, and it gets an @id like the others.
The last crumb is always included in the data, even when the Last option (showLast) hides it from the visible trail.

11.3 The Home Crumb is Always in the Data

Even when you hide the Home link visually (showHome off), Joomla keeps the home page as position 1 in the structured data through a fallback Home crumb. This gives you a clean visible trail and complete machine-readable data at the same time.

11.4 Test Your Markup

After publishing, validate the output with Google's Rich Results Test or the Schema Markup Validator. A valid BreadcrumbList can earn the breadcrumb display in search results.

12. Multilingual Breadcrumbs

12.1 The Home Crumb per Language

On a multilingual site, each language has its own default (home) menu item. The Breadcrumbs module asks for the default item of the current language:

$home = $menu->getDefault($app->getLanguage()->getTag());

So a Dutch page links the Home crumb to the Dutch home, and an English page to the English home. This only works if every active language has its own default menu item. If a language has none, Joomla falls back to the home item for All languages, and the Home crumb points to the wrong home page.

In the menu items list, you can recognise a language's home item by its language flag in the Home column (or a language-code badge if no flag is set). The home item for All languages shows a house icon.

12.2 Avoiding Duplicate Home Entries

On multilingual sites the home menu item can appear twice: once from the Home crumb and once from the menu tree. The default layout detects this and removes the duplicate second entry, so the trail stays clean.

12.3 Translated Labels

Each crumb name comes from the title of the menu item, category or article that the visitor is viewing. On a multilingual site, each language has its own menu items and content, each with its own title. So a Dutch page builds its trail from Dutch titles, and an English page from English titles. Associations are not needed for this: they link translations to each other, for example for the language switcher, but they do not change the trail.

The fixed words come from the module's language file: "Home" (MOD_BREADCRUMBS_HOME) and "You are here:" (MOD_BREADCRUMBS_HERE). Joomla translates them automatically for every installed language. If you fill in the homeText option, that text replaces "Home" in every language. In that case, create a separate Breadcrumbs module per language, each with its own homeText, and set each module's Language field. The easier option is to leave homeText empty and let the language files handle it, or change the wording with a language override.

13. Caching

13.1 Per-Itemid Caching

The Breadcrumbs module has a hidden, fixed itemid cache mode. When module caching is active, Joomla stores one cached copy of the trail per menu item (Itemid) and per combination of access levels. It does not look at the rest of the URL.

Module caching only happens when all of these are true:

Caching is enabled in the Global Configuration.
The module's Caching option is set to Use Global. The default is No caching.
The visitor is not logged in. Logged-in users always get a freshly built trail.

Note that Cache Time is set in seconds, not minutes.

13.2 When to Use Module Caching

Keep the default, No caching. Building the trail is cheap: the module only reads the Pathway that is already in memory, so caching saves almost nothing.
Caching per Itemid can show the wrong trail. Components add crumbs based on the full URL, not only the Itemid. All articles opened from one Category Blog share the same Itemid, so with caching on, every article shows the cached trail of the first article that was visited, including its title.
Only consider Use Global when every page has its own menu item, so the trail comes entirely from the menu tree.
Crumbs based on the logged-in user are safe: Joomla never serves cached modules to logged-in users.
Need speed? Use the System - Page Cache plugin instead. It caches the whole page per full URL, so each article keeps its own correct trail.

14. Common Mistakes and Pitfalls

14.1 No Breadcrumbs Appear

Symptom: there is no trail anywhere on the site.

Fix: publish the Breadcrumbs module, set it to a real template position (such as breadcrumbs in Cassiopeia), and assign it to the right pages.

14.2 The Trail Starts in the Wrong Branch

Symptom: an article shows Home → Wrong Section → Article.

Fix: the wrong Itemid is active. Link to the content through the correct menu item, or give the page its own menu item. Check the category tree too, since article crumbs follow category parents.

14.3 Duplicate Home on Multilingual Sites

Symptom: the trail shows Home → Home → ....

Fix: this happens when the home item appears in both the Home crumb and the menu tree. Modern Joomla removes the duplicate automatically; if you use a custom override, make sure it keeps the de-duplication logic from the default layout.

14.4 A Heading Crumb Has No Link

Symptom: a middle crumb is plain text, not a link.

Fix: this is correct behaviour. Menu items of type Heading or Separator have no page, so Joomla renders them as text. If you need a link there, use a real menu item type instead.

14.5 The Last Crumb Repeats the Page Title

Symptom: the trail ends with the same text as the page heading, which feels redundant.

Fix: turn off the Last option (showLast) to end the trail at the parent.

14.6 Edited the Module Instead of an Override

Symptom: custom breadcrumb markup disappears after a Joomla update.

Fix: never edit files in modules/mod_breadcrumbs/. Put your changes in a template override at templates/[template]/html/mod_breadcrumbs/default.php.

15. Best Practices

If you only remember a few things from this article, remember these:

Publish one Breadcrumbs module and assign it to all pages except the home page. On a multilingual site, only use one module per language if you want a custom Home text per language.
Give the module a clear title, even if you hide it: screen readers announce it as the label of the breadcrumb navigation.
Keep a clean, shallow category tree, because article crumbs follow category parents.
Always link to content through a correct menu item so the Itemid is stable.
Decide once whether to show the last crumb, and keep it consistent across the site.
Keep module caching on No caching. It caches one trail per menu item, which can show the wrong trail on article pages.
Change the look with CSS, and the markup with a template override. Never edit the module files.
Trust the built-in schema.org output, and validate it with Google's Rich Results Test.
On multilingual sites, set a default menu item per language so the Home crumb resolves correctly.

16. Quick Reference

SHOW BREADCRUMBS    Publish mod_breadcrumbs in a template position
HIDE ON HOME        Menu Assignment → All pages except Home
"YOU ARE HERE"      Option showHere (off = location icon)
HOME CRUMB          Option showHome (homeText overrides the word)
LAST CRUMB          Option showLast (off = end at parent)
DATA SOURCE         $app->getPathway() (Pathway object, not a table)
BASE OF TRAIL       Active menu item + its parents (the tree property)
EXTRA CRUMBS        Components call $pathway->addItem(name, link)
ADD A CRUMB (PHP)   $app->getPathway()->addItem('Label', 'index.php?...')
PLUGIN EVENT        onAfterDispatch (after the component's crumbs)
PIPELINE            Router → Menu item → Pathway → Component → Module → Layout
DB TABLES           #__menu (tree), #__modules, #__modules_menu, #__viewlevels
OVERRIDE MARKUP     templates/[tpl]/html/mod_breadcrumbs/default.php
STRUCTURED DATA     schema.org BreadcrumbList JSON-LD, automatic
                    (Home and last crumb included, even when hidden)
CACHING             Default No caching; keep it off
                    (mode itemid: one cached trail per menu item, not per URL)
DEPRECATED API      BreadcrumbsHelper::getList()/getHome() (use getBreadcrumbs()/getHomeItem())

17. Summary

Joomla breadcrumbs are simple on the surface and clever underneath:

Pathway: the internal list of crumbs, rebuilt on every request.
Menu tree: the active menu item and its parents form the base of the trail.
Components: add deeper crumbs such as category and article titles through addItem().
Pipeline: router → menu item → Pathway → component → module → layout.
Module: mod_breadcrumbs reads the Pathway, adds the Home crumb, and renders the visible trail.
SEO: the module emits schema.org structured data automatically.
Caching: keep module caching off, because the cache is per menu item, not per page.
Itemid: the menu item context that decides where the trail begins.

Once you understand that the trail mirrors your menu and category structure, broken breadcrumbs stop being a mystery. They are almost always a symptom of a wrong Itemid, a messy category tree, or a missing menu item.

If your breadcrumbs look wrong, your navigation feels confusing, or you want clean structured data for better search results, it pays to review your menu structure and routing early. Get the menu tree right, and breadcrumbs take care of themselves.

Need help with your Joomla website?

Prefer to solve it together instead of spending hours troubleshooting?

With db8 Website Support, I offer professional paid support for Joomla and YOOtheme Pro. We work together in a live online session, so you can make decisions immediately, see exactly what I do, and learn how your website works along the way.

Get Joomla support

Peter Martin

Joomla Specialist

Peter is a Joomla specialist and a Linux admin for fast, secure and scalable websites.

Help with Joomla?

or YOOtheme Pro, or development?

Stuck with your Joomla website or YOOtheme Pro? Get professional support in a live online session, we solve the problem together and learn along the way.

Contact db8!

Cassiopeia: The Complete Guide to Joomla's Default Template

Choosing Social Media Platforms for Your Joomla Website

Choosing the Best Web Server for Joomla

Configure HTTP Headers in Joomla

Configure Redirects in Joomla

Configuring Email in Joomla

Configuring Joomla

Configuring Joomla Authentication

Configuring Joomla Cache

Configuring Joomla Multilingual Associations

Frequently Asked Questions

What are Joomla breadcrumbs?

Joomla breadcrumbs are a navigation trail that shows where the current page sits in your site structure, from the home page down to the page you are viewing. They are built from the menu tree and the category structure, not from the pages a visitor clicked before.

How do breadcrumbs help SEO?

Breadcrumbs add internal links to parent pages and help search engines understand your site hierarchy. Joomla's Breadcrumbs module also outputs schema.org BreadcrumbList structured data automatically, which Google can use to show the trail in search results.

Can I customize Joomla breadcrumbs?

Yes. The module options let you show or hide the "You are here" label, the Home crumb and the last crumb, and change the Home text. You can change the look with CSS, the wording with language overrides, and the markup with a template override of mod_breadcrumbs.

Are breadcrumbs mobile-friendly in Joomla?

That depends on your template's CSS. In the default Cassiopeia template, the trail wraps onto a new line when it is too long for a small screen. In other templates, check how a long trail looks on a phone, and consider hiding the last crumb to keep it short.

How do I enable breadcrumbs in Joomla?

Go to System → Site Modules → New → Breadcrumbs. Choose a template position (in Cassiopeia: breadcrumbs), set the status to Published, and assign the module to the pages where the trail should appear.

Do breadcrumbs affect site speed?

Hardly. The module only reads the trail that Joomla has already built in memory for the current page, so it adds no extra database queries. That is also why you can leave module caching off for breadcrumbs.

27 June 2026