Module positions in Joomla: why your module does not show up

You create a module, give it a title, fill in the content, press Save, and the front end shows nothing. No error, no empty box, just the page as it was. It is one of the most common support questions on any Joomla site, and the cause is almost never a bug. Somewhere between the module and the template, one setting does not match.

This article goes through those settings in the order that finds the problem fastest, starting with the tool most people never switch on: the module position preview.

See where the positions are: tp=1

A template decides where modules can appear. Each spot has a name, such as sidebar-right or footer, and a module is only rendered if its position name matches one the active template actually outputs. Joomla can show you all positions on a live page, but the option is off by default.

1. Go to System → Site Templates and click the Options button in the toolbar.
2. Set Preview Module Positions to Enabled and save.
3. Open any page on the front end and add ?tp=1 to the address, for example https://example.com/contact?tp=1. If the URL already has a query string, use &tp=1.

Every position the template outputs on that page now gets an outline with its name. Positions the template only renders when they contain a module may not appear at all, which is a clue in itself. When you are done, switch the option off again. Anyone who knows the trick can otherwise see the structure of your template.

The positions Cassiopeia offers

Cassiopeia, the default template in Joomla 4 and 5, has these positions: topbar, below-top, menu, search, banner, top-a, top-b, main-top, breadcrumbs, main-bottom, sidebar-left, sidebar-right, bottom-a, bottom-b, footer, debug, plus error-403 and error-404 for the error page. A third-party template uses its own names. The list is in the template's templateDetails.xml file, and the Position field in the module editor shows it as a dropdown when that template is selected.

Why a module does not show up

Work through this list from top to bottom. On most sites the problem is one of the first three.

1. The position name does not exist in the template

The Position field accepts free text. Type sidebar instead of sidebar-right, or keep a position name from your old Joomla 3 template (position-7 was popular in Protostar), and the module is saved without complaint and never rendered. Open the Position dropdown and pick a name from the section for your active template, instead of typing one.

2. Menu Assignment is set to "No pages"

New modules default to On all pages in recent versions, but modules created by an extension installer or copied from an old site often have No pages or a selection of menu items that no longer exist. Open the Menu Assignment tab and check it. Remember that "the page" means the active menu item. An article reached through a category blog belongs to the blog's menu item, not to some menu item that links directly to that article.

3. A different template style is active on that page

Template styles can be assigned per menu item. If the contact page uses a second style of a different template, it has a different set of positions, and your module may sit in one that this template does not output. Check System → Site Template Styles and look at the Pages column. The same trick is covered from the other side in Styling one menu item differently.

4. Publishing, dates, access and language

• The module is unpublished, or in the trash.
• Start Publishing lies in the future, or Finish Publishing has passed.
• Access is set to Registered or a custom level while you test as a guest. The reverse happens too: Guest modules disappear once you log in.
• On a multilingual site, the module Language is set to one language and you are viewing the other.

5. The module has nothing to show

Several core modules render nothing when they have no content. Latest Articles with an empty category, a Related Articles module on a page without tags or meta keywords, and Breadcrumbs on the home page are the usual examples. The module is working, it just has no output. Point it at a category that has articles to confirm.

6. The template override or chrome hides it

A module layout override in templates/yourtemplate/html/mod_xxx/ can contain an early return or a CSS class that hides output. Set the module's Layout on the Advanced tab back to the default to rule this out. The same goes for a custom module chrome or a CSS rule such as display: none on the position container. The browser's inspector shows whether the HTML is in the page and only hidden, or absent altogether.

7. Cache

With Conservative or Progressive caching on, or the Page Cache plugin enabled, guests may get the old page for a while. Clear the cache in System → Clear Cache, and remember that a hosting proxy cache (SiteGround, Cloudflare) sits in front of that and has its own purge button.

Find orphaned modules in the module list

In Content → Site Modules, open Filter Options and set the position filter to None. That shows every module without a position, which usually means modules left behind after a template change. Filtering by a position that your current template does not have (old position-7, for example) finds the rest. Move them to a real position or trash them, so the list reflects what visitors actually see.

After a template switch

Changing templates is the moment when most modules go missing at once, because the new template uses different position names. Before you switch, make a list of every published module and its position. Afterwards, filter by each old position name and move the modules in one go with Actions → Batch, which can set a new position for a whole selection. If you only want to change the look of Cassiopeia rather than replace it, a child template keeps all positions intact; see Child templates in Joomla.