Cassiopeia: The Complete Guide to Joomla's Default Template

1. The Basics

1.1 What is Cassiopeia?

Cassiopeia is the standard site template that ships with every Joomla installation since Joomla 4 (the backend uses its own template, Atum). It lives in templates/cassiopeia/ with its assets in media/templates/site/cassiopeia/, and it is built on Bootstrap 5, with accessibility and performance as explicit design goals: semantic landmarks, keyboard-friendly navigation, no external font or script requests by default.

1.2 The Philosophy: a Plain Canvas

Cassiopeia looks deliberately unspectacular. It is not trying to be a page-builder theme; it is a clean, standards-compliant canvas that you shape with template options, module positions, CSS, and overrides. That plainness is a feature: there is very little to fight against, and everything Joomla can do - every component view, every module - renders correctly in it out of the box.

1.3 When Cassiopeia is Enough (and When Not)

• Enough: content sites, blogs, documentation, organisation and business sites where clear typography and structure matter more than visual fireworks. With a child template and some CSS, Cassiopeia carries these well.
• Consider something else: heavily designed marketing sites built by drag-and-drop, or projects standardised on a template framework. Even then, what you learn from Cassiopeia transfers: positions, styles, overrides, and asset handling work the same everywhere.

In my own client projects I often reach for YOOtheme Pro, a commercial template with a visual drag-and-drop builder, when the design goes beyond what Cassiopeia offers comfortably. Its builder composes full page layouts without PHP overrides, its Dynamic Content feature pulls Joomla articles and custom fields straight into any layout, and ready-made layouts shorten the path from empty site to finished design. After handover, editors maintain pages themselves without needing a developer for every change. The trade-offs: a yearly license, some lock-in to the builder's markup, and a bit heavier pages than a hand-tuned Cassiopeia child template - for a lean content site, the free default remains hard to beat.

3. Module Positions

3.1 The Position Map

Cassiopeia defines 18 positions. The layout skeleton, top to bottom:

topbar
below-top
[ brand ]  menu   search
banner
top-a          (card)
top-b          (card)
┌──────────────┬────────────────────┬───────────────┐
│ sidebar-left │ breadcrumbs        │ sidebar-right │
│    (card)    │ main-top   (card)  │    (card)     │
│              │ [ component ]      │               │
│              │ main-bottom (card) │               │
└──────────────┴────────────────────┴───────────────┘
bottom-a       (card)
bottom-b       (card)
footer

Positions marked (card) use Cassiopeia's card chrome by default: modules there render inside a styled box with the title as a card header. The structural positions (topbar, menu, breadcrumbs, footer, ...) use no chrome. Sidebars only appear when a module is published in them - an empty sidebar costs no space.

3.2 Three Special Positions

• debug: where the debug console renders when Debug System is on.
• error-403 and error-404: positions that render only on error pages. Publish a search module, a sitemap menu, or a friendly custom HTML module here and your 404 page becomes helpful instead of a dead end - no code required.

3.3 Seeing Positions Live

Enable Preview Module Positions in the Templates options, then append ?tp=1 to any frontend URL. Every position renders with an outline and its name - the fastest way to answer "where is top-b, really?".

A detail from the source code: Joomla reads the parameter with getBool('tp') and its boolean filter is a plain PHP cast, so any value except 0 or an empty string counts as "on". ?tp=peter-was-here switches the preview on just as well as ?tp=1 - and, more surprisingly, so does ?tp=false.

5. Customising with user.css and user.js

5.1 Built-in, Update-proof Custom Code

Cassiopeia's asset definitions register two optional files that you create:

media/templates/site/cassiopeia/css/user.css
media/templates/site/cassiopeia/js/user.js

If they exist, Joomla loads them automatically - and thanks to their asset weight, user.css loads after the template's own stylesheet, so your rules win without !important battles. Joomla updates never touch these files. For small and medium customisations - colours, spacing, fonts, hiding elements - this is all you need.

5.2 A Sensible user.css Starting Point

:root {
    --cassiopeia-color-primary: #1a3866;   /* your brand colour */
    --cassiopeia-color-link: #1a3866;
}

.site-grid {
    row-gap: 2rem;                          /* breathing room */
}

Cassiopeia exposes its design as CSS custom properties, so most restyling is redefining variables rather than overriding selectors. Check colors_standard.css for the full list of variables it sets.

5.3 Where user.css Stops

CSS changes appearance, not markup. The moment you need different HTML - another heading structure, extra wrappers, reordered elements - you have left user.css territory and entered template overrides (see the Focus On article about template overrides). And when your customisations grow beyond a handful of files, collect them in a child template.

7. Template Styles in Practice

7.1 One Template, Many Styles

A template style is a saved set of option values. Duplicate the Cassiopeia (or child) style in System → Site Template Styles, change its options - another logo, fluid instead of static, a different colour scheme - and assign it to specific menu items via the style's Menu Assignment tab. Joomla then renders those pages with the other style.

7.2 What Styles Solve

• A landing-page section with a fluid, full-width layout while the rest stays static.
• A campaign or sub-brand area with its own logo and colours.
• A quiet, distraction-free style for documentation pages.

Styles cost nothing at runtime and need no extra files - they are rows in #__template_styles with a JSON params column. Before duplicating a whole template for a visual variation, check whether a second style does the job.

9. Under the Hood (Developer View)

9.1 The File Anatomy

9.2 The Asset Graph

Cassiopeia is a textbook example of the Web Asset Manager. Its joomla.asset.json defines named assets with dependencies: template.cassiopeia.ltr/.rtl (the main stylesheet per text direction), template.active (an alias the framework resolves to the active template), and template.user - the user.css/user.js pair from section 5, declared with weight 500 so it loads last. When your own extension needs to load after the template's CSS, depend on template.active instead of hard-coding file paths.

9.3 Reading index.php

The template's index.php is short and readable, and three details reward a look: the logo fallback chain (image, then siteTitle, then site name - exactly the order from section 2.2), the conditional wrappers that only render a position's markup when a module is published there, and the style="card" versus style="none" chrome choices per position. If you build your own template or child index.php, Cassiopeia is the reference implementation to imitate.

9.4 What Powers the Frontend

Bootstrap 5 provides the grid and components, metismenu the menu interactions - both shipped locally, no CDN. The template adds its own CSS on top; there is no build step to run on the server, and nothing phones home. That is worth preserving in your customisations: keep assets local, and your site stays fast and GDPR-quiet.

9.5 The SCSS Sources

Cassiopeia even ships its stylesheet sources: media/templates/site/cassiopeia/scss/ contains template.scss, template-rtl.scss, and offline.scss, importing Bootstrap and the template's own partials. The live site never compiles them - it loads the prebuilt CSS - but they are valuable in two ways: as the authoritative reference for how the template's styles are constructed, and as the starting point for a fully custom build (compile with a Sass toolchain in your development environment, ship the result as your child template's stylesheet). For everyday customisation, user.css and the CSS variables remain the right tool; reach for a custom SCSS build only when you are effectively designing your own template on Cassiopeia's foundation.

11. Cassiopeia and the Web Services API

Template styles - including every Cassiopeia option from section 2 - are manageable over REST. The styles endpoints (v1/templates/styles/site) expose each style with its params JSON, so a provisioning script can create a fluid landing-page style or switch the site's default style remotely:

curl -H "X-Joomla-Token: <token>" \
     https://example.test/api/index.php/v1/templates/styles/site

The template's files - user.css, overrides, a child's html/ folder - are filesystem artefacts outside the API's reach; deploy them with git or rsync as part of your normal deployment. And as with all presentation, none of Cassiopeia affects what the API returns: API responses are raw data, whatever template is active.

13. Common Mistakes and Pitfalls

13.1 Editing Cassiopeia's Files Directly

Symptom: custom CSS or template edits disappeared after a Joomla update.

Fix: Joomla updates replace templates/cassiopeia/ and its media folder. Redo the work in the update-proof layers: user.css, a child template, overrides. Then it never happens again.

13.2 user.css Does Not Load

Symptom: the file exists but nothing changes.

Fix: check the exact location and name: media/templates/site/cassiopeia/css/user.css (or the child's media folder when a child style is active - a user.css in the parent is not loaded for a child). Then clear the cache and force-reload the browser.

13.3 The Logo Options Fight Each Other

Symptom: you set a title but an image shows, or the site name appears instead of your title.

Fix: remember the order: image beats title beats site name. Clear the logoFile field if you want the text title; set brand off to hide the block entirely.

13.4 Modules Missing Their Box (or Having One Too Many)

Symptom: a module renders with an unexpected card, or without the card you wanted.

Fix: the position determines the default chrome (section 3.1), and each module can override it under Advanced → Module Style. Set it explicitly to card or noCard when the position default does not fit.

13.5 Customising the Parent While a Child is Active

Symptom: overrides or CSS added to Cassiopeia have no effect.

Fix: the active style belongs to the child, and the child's files win. Move the customisation into the child - which is where it belonged anyway.

13.6 Expecting a Page Builder

Symptom: frustration that Cassiopeia has "so few settings" compared to commercial templates.

Fix: Cassiopeia's settings are deliberately few; its power sits in styles, positions, user.css, and overrides. Invest a day in those four mechanisms and you have more control than most template control panels give - with less lock-in.

15. Quick Reference

FILES        templates/cassiopeia/            index.php, manifest, html/
             media/templates/site/cassiopeia/ css, js, fonts
             user files: css/user.css + js/user.js  (load last, update-proof)

OPTIONS      brand / logoFile / siteTitle / siteDescription
             logo order: image > title > site name
             fluidContainer, stickyHeader, backTop
             useFontScheme (local Roboto), colorName (standard/alternative)

POSITIONS    topbar below-top menu search banner
             top-a top-b (card)
             sidebar-left | breadcrumbs main-top [component]
             (card)       | main-bottom (card)  | sidebar-right (card)
             bottom-a bottom-b (card) footer
             special: debug, error-403, error-404
             preview: ?tp=1 (enable in Templates options)

MENU         html/mod_menu: dropdown-metismenu (horizontal)
                            collapse-metismenu (vertical)
             search position = compact header search slot

CHILD        manifest: inheritable = 1
             System > Site Templates > Create Child Template
             child html/ + child user.css win over parent

STYLES       duplicate style > change options > Menu Assignment
             stored in #__template_styles (params JSON)
             API: v1/templates/styles/site

CHROMES      card (boxed, title as header) / noCard
             per module: Advanced > Module Style

RULES        never edit cassiopeia files - child/user.css/overrides
             assets local, depend on template.active