Module positions in the Cassiopeia template for Joomla

Module positions in the Cassiopeia template for Joomla

Cassiopeia remains the default front-end template shipped with Joomla 4 and Joomla 5, and as of 2026 it continues to be the baseline that most Joomla site builders start from before customising or switching to a child template. Understanding its module position system is foundational whether you are building a new site on Joomla 5.x or maintaining a site that migrated from an older version.

TL:DR – I keep looking for module positions in the Cassiopeia template for Joomla so I documented it.

Module positions

Module positions in Cassiopeia are named placeholders that control where content rendered by published modules appears on a page. The workflow is straightforward: assign a module to a named position, choose which menu items or pages it should appear on, publish it, and Joomla takes care of injecting the module's output into the correct location in the page layout. Positions that have no published modules assigned to them simply collapse — they produce no markup and consume no space in the rendered HTML.

In Joomla 5, the module assignment interface has been refined with a cleaner administrator UI, but the underlying position names in Cassiopeia are unchanged from Joomla 4, which means sites migrated from Joomla 4 to 5 retain all their module placements without any manual remapping. Child templates built on Cassiopeia also inherit these positions automatically unless the child template's templateDetails.xml explicitly overrides them.

Module chrome

Module chrome refers to the wrapping markup and styling applied around a module's raw output. Cassiopeia ships with three chrome options:

• none — outputs the module content with no additional wrapper markup, giving you full control via your own CSS.
• card — wraps the module in a Bootstrap card component, adding a visible bordered container with a header showing the module title.
• noCard — suppresses the card container while still allowing the module title to render, useful when you want a title but a flat layout.

Since Joomla 5 moved to Bootstrap 5 as its bundled CSS framework, the card chrome renders Bootstrap 5 card markup. If you are using a custom or third-party template that bundles a different CSS framework, you may need to override the chrome files in your child template's html/layouts/chromes/ directory to match your framework's card conventions. The Joomla core team has also signalled that additional chrome options may be introduced in future minor releases, so it is worth checking the release notes when upgrading.

Position layout overview

The table below maps out all named positions in Cassiopeia and their approximate location in the page layout. Positions in the same row share horizontal space and will sit side by side when multiple modules are assigned to them; Joomla distributes the available width equally across modules in the same position by default, though you can override column widths through module parameters.

Key positions explained

topbar and below-top

The topbar position sits above everything else on the page, making it well suited to utility content such as language switchers, login links, or accessibility tools. The below-top position sits immediately beneath it and is commonly used for site-wide notices or promotional banners that need to appear above the main navigation but below any utility bar.

brand, menu, and search

These three positions form the header row of the template. The brand position spans the full width and is where Cassiopeia renders the site logo and name by default, driven by template parameters rather than a module — though you can place additional modules here. The menu and search positions sit at opposite ends of the navigation row, creating the classic logo-left, search-right layout that Cassiopeia ships with out of the box.

sidebar-left and sidebar-right

Both sidebar positions flank the main content column. Cassiopeia's layout is responsive: when a sidebar has at least one published module, the main content column narrows to accommodate it; when both sidebars are populated, the content column narrows further. On smaller viewports the sidebars stack above or below the main content area depending on their position in the source order. This behaviour is driven by Bootstrap 5's grid system and requires no additional configuration.

main-top and main-bottom

These positions inject module output directly above and below the main component output area — useful for contextual calls to action, related-content modules, or advertising units that should appear close to the article or component content without sitting in a sidebar.

debug

The debug position is reserved for Joomla's built-in Debug module. It renders at the very bottom of the page and is only visible when the Joomla debug system is enabled. It should not be used for general-purpose modules.

Working with child templates

One of the most significant workflow improvements introduced alongside Joomla 4 and carried forward into Joomla 5 is native child template support. Rather than hacking Cassiopeia's core files — which would be overwritten on every Joomla update — you can create a child template that inherits all of Cassiopeia's positions, layouts, and chrome files, then selectively override only the files you need to change. This approach keeps your customisations update-safe and makes it straightforward to track what you have modified. The Joomla administrator includes a one-click interface for creating a Cassiopeia child template, found under System > Site Templates.

If you need module positions that Cassiopeia does not provide out of the box, you can add them by copying and editing the relevant layout files in your child template and registering the new positions in your child template's templateDetails.xml. The Module Preview feature in the Joomla administrator — toggled via the eye icon in the Template Manager — will then show your custom positions alongside the built-in ones, making it easy to assign modules without guesswork.