Category: Joomla

Joomla 5 and 6 can upload and display WebP and AVIF images (AVIF since Joomla 5.0), and they lazy-load images that have a known width and height. Joomla core does not convert JPG or PNG to WebP or AVIF, and it does not create responsive image sizes. To serve next-gen formats you need one of four things: a Joomla extension, a server rewrite rule, a CDN, or manual conversion. Which one fits depends on how big the site is and what your hosting allows.

Quick answer

• Native support: Joomla 5 and 6 accept WebP and AVIF in the Media Manager and render them like any other image. Nothing converts automatically.
• To convert: an extension is easiest for sites where editors keep uploading. A server rule or CDN suits developers. Manual conversion works for a handful of images.
• AVIF needs server support: PHP 8.1+ with GD built with AVIF, or Imagick with AVIF. If you don’t have it, start with WebP.
• Measure it: run PageSpeed Insights before and after, check the LCP element, then watch Search Console’s Core Web Vitals report.

Does Joomla support WebP and AVIF natively?

Yes for displaying them, no for creating them. This is what Joomla core does with images, by version, based on the merged code changes and release notes:

For everything else in the latest release, see our Joomla 6.2 guide.

How to allow AVIF on a site installed before Joomla 5.0

If an AVIF upload is rejected, your site probably kept its old Media settings when you upgraded. In Joomla 5 and 6:

1. Go to System → Global Configuration → Media (or Content → Media → Options).
2. Add avif to Allowed Extensions and to Legal Image Extensions (File Types). Check that webp is there too.
3. Add image/avif (and image/webp if missing) to Legal MIME Types.
4. Save, then upload a test AVIF file in Content → Media.

These are the field labels in the Joomla 6.2 code. On a fresh 6.2 install, all three fields already include WebP and AVIF.

Why does it matter for PageSpeed and Core Web Vitals?

PageSpeed Insights and Lighthouse flag JPG and PNG files that could be smaller (“Serve images in next-gen formats”, or “Improve image delivery” in newer Lighthouse versions). On many Joomla templates the hero or intro image is the Largest Contentful Paint (LCP) element, so its file size affects how fast the page looks loaded. Google’s guidance is that a good LCP is 2.5 seconds or less for at least 75% of page visits.

Google reports that lossy WebP images are 25–34% smaller than comparable JPEGs at equal SSIM quality, and lossless WebP is 26% smaller than PNG. Your results depend on the image and the quality setting, so compare sizes on your own files. Google also says good Core Web Vitals line up with what its ranking systems seek to reward, but content relevance comes first. Converting images will not by itself move a page up.

What do you need on the server before converting?

A quick check from the command line, if you have SSH:

php -r 'print_r(array_intersect_key(gd_info(), array_flip(["GD Version","WebP Support","AVIF Support"])));'

On our PHP 8.4 test server this printed [WebP Support] => 1 and [AVIF Support] => 1. If AVIF shows as empty, use WebP for now. To raise the limits, see our Joomla PHP.ini settings guide.

Which conversion method should you use?

Method 1: How do you convert images with a Joomla extension?

Image extensions on the Joomla Extensions Directory work in one of three ways:

• On page view, plus bulk: rewrites image URLs in the page output, creates WebP/AVIF copies when needed, and can convert whole folders in advance.
• On upload only: converts files as they’re uploaded through the Media Manager. Images already on the site are left alone.
• Scheduled bulk optimisers: run as Joomla scheduled tasks, and some send images to an external API.

Some examples, as described on their JED listings (checked 19 October 2026):

Disclosure: Infyways builds and sells WebP Converter through JoomlaX, our extension store. We’ve built 125 Joomla extensions since 2010. The steps below use it because it’s the one we know first-hand. The other extensions can be a better fit, for example if you only need conversion on upload.

Setting up WebP Converter, step by step

1. Install: unzip the downloaded WebPConverter_UNZIP.zip on your computer, then upload only the inner plg_system_webpconverter_…zip in System → Install → Extensions.
2. Enable: in System → Plugins, search “WebP Converter” and enable System – WebP Converter.
3. First settings: in General Settings, set Image Format to WebP Only, WebP Quality to about 70–80, and leave Lightweight Processing on and Debug Mode off. Save.
4. Test one folder: on the Image Management tab, tick one small folder, choose WebP Only and click Generate Images. With the default settings, images/stories/photo.jpg gets a copy at images/webp/stories/photo.webp, and the original stays where it is.
5. Check: clear the Joomla cache (and the CDN cache), open the page, and search the page source for .webp.
6. Add AVIF later: once WebP works and your server supports AVIF, switch Image Format to Both. Browsers that support it then get AVIF first, then WebP, then the original.

If PageSpeed still lists JPG URLs in Open Graph or schema tags, turn on Replace Image URLs Globally. You can exclude logos, animated GIFs, checkout pages or whole folders under Exclusion Settings. Full settings are in the WebP Converter documentation, and plans are on the product page.

Method 2: Can you serve WebP with .htaccess instead of a plugin?

Yes, if the WebP/AVIF files already exist next to the originals. The server checks the browser’s Accept header and quietly returns the smaller file at the same URL. Joomla, your articles and your template don’t change.

Step 1: create sibling files. This naming keeps photo.jpg and photo.png from colliding:

cd images
find . -type f \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' \) | while read f; do
  [ -f "$f.webp" ] || cwebp -quiet -q 80 "$f" -o "$f.webp"
  [ -f "$f.avif" ] || avifenc -q 60 "$f" "$f.avif" >/dev/null   # optional
done

Step 2: add the rules to Joomla’s .htaccess, in a block of their own just above the line ## These directives are only enabled if the Apache mod_rewrite module is enabled:

<IfModule mod_mime.c>
  AddType image/webp .webp
  AddType image/avif .avif
</IfModule>
<IfModule mod_rewrite.c>
  RewriteEngine On
  # AVIF first, if the browser accepts it and photo.jpg.avif exists
  RewriteCond %{HTTP_ACCEPT} image/avif
  RewriteCond %{REQUEST_FILENAME}.avif -f
  RewriteRule ^(.+)\.(jpe?g|png)$ $1.$2.avif [T=image/avif,L]
  # Otherwise WebP, if accepted and photo.jpg.webp exists
  RewriteCond %{HTTP_ACCEPT} image/webp
  RewriteCond %{REQUEST_FILENAME}.webp -f
  RewriteRule ^(.+)\.(jpe?g|png)$ $1.$2.webp [T=image/webp,L]
</IfModule>
<IfModule mod_headers.c>
  <FilesMatch "\.(jpe?g|png)$">
    Header append Vary Accept
  </FilesMatch>
</IfModule>

What we saw when testing it (Apache 2.4, one 1600×900 test JPG): the same /images/hero.jpg URL returned image/avif to an AVIF-capable Accept header, image/webp to a WebP-only header, and the original image/jpeg to */*. All three responses carried Vary: Accept. Try it on staging first, and confirm with curl -I -H "Accept: image/webp" https://example.com/images/hero.jpg.

• New uploads don’t get siblings until you run the script again, for example as a nightly cron job.
• Caches: any page or proxy cache must respect Vary: Accept. Otherwise a browser that only handles JPG could be served a cached WebP.
• Cloudflare: its docs say Polish may not run on responses with any Vary header other than Accept-Encoding. Use either this rule or Polish, not both.
• nginx has no .htaccess. Use a map $http_accept with try_files $uri$suffix $uri in the server block instead.

More about Joomla’s rewrite file: Joomla .htaccess guide.

Method 3: Can a CDN convert Joomla images for you?

Yes. Image CDNs check what each browser accepts at the edge and return a smaller format, so your server does no conversion work. For example, Cloudflare Polish keeps your image URLs and, with its WebP option on, serves a WebP version when the browser accepts it and the file comes out smaller. Polish is on Pro plans and above, and its docs note it won’t convert a JPEG when that would make the file bigger. Other image services (Bunny Optimizer, imgix and similar) work in a similar way. Check what your plan includes.

• Pros: no load on your server, no Joomla changes, and new uploads are covered automatically.
• Cons: it costs money, you get less control per folder, and images on other domains aren’t covered. You also depend on the vendor’s rules about when to convert.

Method 4: How do you convert images manually?

For a small brochure site or a redesign with a few dozen images:

1. Convert in the browser with our free image to WebP converter, shrink files with the bulk image compressor, or use cwebp / avifenc on your computer.
2. Upload the .webp files in Content → Media.
3. Update every article image, module and template reference to the new file.
4. Keep the originals backed up offline.

This doesn’t scale: every new upload starts the problem again, and older browsers get no fallback.

How do you keep LCP fast once images are converted?

Converting the format is only half the job. Joomla core doesn’t handle these steps for you:

• Give images a width and height. Joomla only adds loading="lazy" when it knows both, and setting them also stops layout shift (CLS). Images picked through the media field store their size in the URL (#joomlaImage://…?width=…&height=…).
• Don’t lazy-load the LCP image. A hero image that appears straight away should load right away. Use a template override to set loading="eager" and fetchpriority="high", or add a <link rel="preload" as="image">.
• Size images for the layout. A 4000 px photo in an 800 px column is wasted bytes even as WebP. Joomla’s Media Action – Resize plugin can cap upload sizes. For srcset, use a template override or an extension that creates the extra sizes.
• Check CSS background images. Templates often load hero images from CSS, where only a server rule, a CDN or an extension that rewrites CSS backgrounds will swap the format.

For caching, compression and the rest of the stack, see the full Joomla speed guide.

WebP or AVIF: which should you use on Joomla?

Gains vary a lot by image, so run a few of your own images through both formats at your chosen quality and compare file size and appearance before converting a whole site.

How do you check that it worked?

1. DevTools → Network: reload the page, click an image and check that the content-type is image/webp or image/avif.
2. PageSpeed Insights: run the mobile test on pagespeed.web.dev. Check the next-gen image and image-sizing audits, and which element is the LCP.
3. Field data: the “Discover what your real users are experiencing” panel uses Chrome UX Report data, a rolling 28-day window, so it changes slowly.
4. Search Console → Core Web Vitals: once you’ve fixed the issue, use “Validate fix” and allow about four weeks for the field data to update.
5. Purge caches: clear Joomla’s cache, your page-cache extension and the CDN, or you may keep testing the old JPG.

When should you get help?

Image-heavy shops, sites that use page builders with CSS background heroes, multilingual sites behind a CDN, and template overrides for srcset or fetchpriority are where DIY fixes usually stall. You can hire a Joomla developer from Infyways; a senior engineer replies within 12 hours.

Frequently asked questions

Does Joomla convert images to WebP automatically?

No. Joomla 5 and 6 can upload and display WebP (and AVIF since 5.0), but core doesn’t convert JPG or PNG files. Use an extension, a server rewrite rule or a CDN.

Does Joomla 6.2 add WebP or AVIF features?

No. Joomla 6.2 (released 13 October 2026) brought a TinyMCE picker that opens the Media Manager and separate image/figure CSS classes, but no format conversion.

Can I upload AVIF to the Joomla Media Manager?

Yes, since Joomla 5.0 on new installs. Older sites may need avif and image/avif added under System → Global Configuration → Media. WebP and AVIF can’t be edited in the media editor.

Does Joomla lazy-load images?

Yes. Joomla 4 and later add loading="lazy" to images rendered through the core image layout when the width and height are known. Editors can also choose lazy loading when inserting images.

What do I need on the server for AVIF?

PHP 8.1 or later with GD built with AVIF support, or Imagick with AVIF. Check phpinfo for “AVIF Support”. If it’s missing, start with WebP.

Can I serve WebP without a plugin?

Yes. Pre-convert the images, then use an .htaccess or nginx rule that serves the .webp file to browsers that accept it, with Vary: Accept. A CDN that converts at the edge also works.

Will converting delete my original images?

Not with converters that write separate copies. Some upload-time converters have an option to remove originals, so check that setting before a bulk run and keep a backup.

Why does PageSpeed still show JPG after converting?

Usually because of a cached page or CDN, a CSS background image, or Open Graph and schema tags that still point to the JPG. Purge all caches and turn on your converter’s URL-replacement option if it has one.

Joomla Redirect Guide: 301, com_redirect, .htaccess, and nginx

A Joomla redirect sends visitors and crawlers from an old URL to a new one with an HTTP status code (usually 301). Joomla gives you three practical layers: server rules (.htaccess, nginx, or IIS) that run before PHP, the com_redirect component that runs after a 404, and Global Configuration switches that control how Joomla builds links. Pick the layer that matches whether the old URL still returns 200 or already 404s.

Redirects are not a cosmetic tweak. They are how you keep rankings when you rename an article, retire K2, force one hostname, or move HTTP to HTTPS without splitting authority across two URLs. Google treats a proper 301 as a strong signal to consolidate to the destination: Consolidate duplicate URLs.

This guide is the full map for Joomla 4, 5, and 6. For the "I saved a 301 and nothing happened" checklist, see Joomla 301 redirects not working.

Server rules run first. com_redirect only fires when Joomla has already decided the path is a 404.

What you will learn

• What 301, 302, and 307 mean in Joomla
• When to use .htaccess, nginx, com_redirect, or neither
• How to enable System – Redirect and publish rows in System → Redirects
• Exact .htaccess rules for www, non-www, and HTTP to HTTPS
• nginx and IIS equivalents when there is no .htaccess
• How to test headers, avoid redirect chains, and protect SEO after a migration

301, 302, and what Joomla actually sends

com_redirect defaults to 301 unless your Joomla version exposes per-row status codes under Redirects → Options. Server rules use [R=301] in Apache or return 301 in nginx.

A Menu Item Alias is not a redirect. It shows the same article at a second menu path while both URLs can still 200. Aliases are navigation. Redirects are HTTP responses. If two real menu items point at one article, you have duplicate URLs until you unpublish one or 301 the loser: Joomla duplicate URLs.

Pick the right layer

Official component help: Redirects: Links (Joomla 5) and Redirects: New or Edit. Stock Apache snippets live in preconfigured htaccess.

If the old URL still loads a page, com_redirect never runs. Fix that at the server or unpublish the route.

Step 1: Set up com_redirect (Joomla 4, 5, and 6)

Use the component when the expired path is already a 404 and you want to manage dozens of mappings in the administrator.

Enable the plugin (not optional)

1. System → Plugins → search System – Redirect → Enable.
2. On fresh installs this plugin is often disabled. Rows in System → Redirects do nothing until it is on.

Do not confuse it with System – SEF. SEF builds pretty links. It does not send 301s for dead paths.

Create a redirect row

1. System → Redirects → New.
2. Expired URL: the full old address as you would type it (https://www.example.com/old-alias).
3. New URL: the full destination.
4. Status: Enabled (published). Collected 404s stay disabled until you add a New URL and publish.
5. Save.

Optional: turn on Collect URLs in the plugin so 404s appear in the list for you to map. Collection is logging, not redirecting.

Regex and bulk work

• Enable Regular expressions on a row when you need a pattern (example: all /blog/2019/ paths). Test one URL before importing hundreds.
• After a K2 removal, map /component/k2/... to new com_content URLs as part of Migrate K2 to Joomla articles. Do not leave public 404s while you "collect later."
• Joomla expects Use URL Rewriting on and a working rewrite file, or matching is unreliable. See Joomla index.php still in URLs.

If a row is published and the old URL still shows the old page, a menu item or alias is still serving it. com_redirect cannot help until that route 404s or you move the job to .htaccess.

Step 2: Redirect www and non-www in .htaccess

Pick one canonical host (www or bare) and 301 everything else. This belongs in server config, not in com_redirect.

Joomla ships a commented block in .htaccess labeled custom redirects. Place rules after RewriteEngine On and before the Joomla core rules, or inside the documented custom section from preconfigured htaccess.

Bare → www (replace example.com):

RewriteEngine On
RewriteCond %{HTTP_HOST} ^example.com [NC]
RewriteRule ^(.*)$ https://www.example.com/$1 [L,R=301]

www → bare:

RewriteEngine On
RewriteCond %{HTTP_HOST} ^www.example.com [NC]
RewriteRule ^(.*)$ https://example.com/$1 [L,R=301]

Notes:

• Use your real domain. Escape dots in the host (example.com).
• If you also need HTTP → HTTPS, chain both conditions or use one rule that targets the final https:// host.
• [NC] makes the host match case-insensitive. [L] stops processing. [R=301] sends the permanent redirect.

After editing, purge CDN cache and test in a private window. The address bar should show your chosen host on the first hop.

Step 3: Force HTTPS at the server and in Joomla

Server (Apache / LiteSpeed)

Below RewriteEngine On, when SSL is working:

RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [L,R=301]

Better: combine host canonicalization and HTTPS in one rule set so you do not create a chain (http://example.com → https://example.com → https://www.example.com).

Joomla Global Configuration

System → Global Configuration → Server → Force HTTPS: set to Entire Site once the certificate is valid. That makes Joomla generate https:// links in HTML. It does not always redirect a visitor who manually types http://. Keep the server rule for that.

Step 4: Single-path and migration redirects in .htaccess

When one old path still 200s but must point elsewhere:

Redirect 301 /old-folder/page https://www.example.com/new-alias

Or with mod_rewrite:

RewriteRule ^old-alias/?$ https://www.example.com/new-alias [L,R=301]

Use this for:

• Renamed menu aliases while the old menu item still exists
• /index.php/seo-tips → /seo-tips after SEF is fixed
• Retired microsite folders

For large content moves, pair server rules for structural changes with com_redirect rows for long-tail aliases that already 404.

Step 5: nginx and IIS when Joomla has no .htaccess

nginx (inside the server block for the site):

# bare to www + HTTPS (adjust host names)
if ($host = example.com) {
    return 301 https://www.example.com$request_uri;
}
if ($scheme = http) {
    return 301 https://$host$request_uri;
}

Official Joomla nginx notes: Nginx. You still need try_files so SEF works: details in Joomla index.php URLs.

IIS: rename web.config.txt to web.config, install URL Rewrite, and add equivalent rules. Joomla documents IIS rewriting alongside Apache in Enabling SEF URLs.

Step 6: Test headers, chains, and loops

1. Browser Network tab → first document request → Status should be 301 (or 302 if intentional) with a Location header pointing at the final URL.
2. Command line: curl -I https://www.example.com/old-path and read HTTP/1.1 301 plus Location:.
3. Avoid chains longer than one hop (/a → /b → /c). Google will follow them but dilutes signals. Point /a straight to /c.
4. Loops (/old → /new → /old) crash the browser. Usually a com_redirect New URL points back at the expired path.
5. Clear Joomla cache and any CDN. Cached 404 HTML can hide a redirect you just published.

Canonical tags complement redirects but do not replace them when both URLs still 200: Joomla canonical URL problems.

Redirect mistakes that still waste SEO

Key takeaways

1. 301 is the default for permanent Joomla URL changes that should pass ranking signals.
2. Server rules handle www, HTTPS, and paths that still return 200. com_redirect handles paths that already 404.
3. Enable System – Redirect. The component UI alone is not enough.
4. Publish redirect rows. Collected 404s are a log until Enabled with a New URL.
5. Match the full expired URL (scheme, host, slash) or canonicalize host at the server.
6. Test with response headers, not only whether the browser lands on the right page.
7. After migrations, map old aliases before you declare SEO done. Broader cleanup: Joomla on-page optimization and Joomla SEO services.

Frequently asked questions

What is a 301 redirect in Joomla?

An HTTP response that tells browsers and crawlers a URL moved permanently. Joomla can send it via com_redirect after a 404, or via .htaccess, nginx, or IIS before PHP runs.

Should I use com_redirect or .htaccess?

Use .htaccess (or nginx/IIS) for www, HTTPS, and any old URL that still loads. Use com_redirect when the old path already 404s, such as retired article aliases.

How do I redirect non-www to www in Joomla?

Add Apache rewrite rules after RewriteEngine On in .htaccess, or the nginx/IIS equivalent. Do not rely on com_redirect for hostname changes while both hosts still 200.

How do I redirect HTTP to HTTPS in Joomla?

Force HTTPS in Global Configuration → Server for link generation, and add a server 301 from http:// to https:// so manual HTTP visits redirect too.

Why is my Joomla 301 redirect not working?

Usually the System – Redirect plugin is off, the row is unpublished, or the old URL still returns 200. Full checklist: Joomla 301 redirects not working.

Does Joomla redirect preserve SEO?

A correct 301 tells search engines to consolidate signals to the new URL. Chains, 302s, and duplicate 200 URLs undermine that.

Can I bulk import redirects in Joomla?

Yes on many Joomla 4/5/6 builds via System → Redirects import (CSV). Test a few rows, then import. Regex rows need extra care.

Is a menu alias the same as a redirect?

No. An alias serves the same content at a second menu path. Both can 200. A redirect returns 301/302 and stops serving the old URL.

What about IIS servers?

Rename web.config.txt, install URL Rewrite, and add host and HTTPS rules there. com_redirect still works for 404 paths on IIS.

Where do I put custom .htaccess redirects?

Use the custom redirects section documented in Joomla's preconfigured htaccess, after RewriteEngine On, without breaking the core Joomla rewrite block.

To create a custom 404 page in Joomla 5 or 6, publish a Custom HTML (or other) module in the error-404 position on Cassiopeia or a child of Cassiopeia. Joomla still returns HTTP 404. The module replaces the default message inside error.php. Do not header('Location: …') to a normal article. That turns a missing URL into a 302 or 200, which is what the 2019 version of this page did, and it is the wrong signal for Google.

On Joomla 4 there is no error-404 position in core Cassiopeia. You copy error.php into a child template and edit that copy, or you add the same module include that Joomla 5 shipped. Known broken URLs that should move, not 404, belong in the Redirect component.

A custom 404 is still a 404. Pretty HTML does not mean a 200 OK.

What you will learn

• Why a redirect to an article is not a 404 page
• How Cassiopeia error-404 and error-403 modules work (Joomla 5.0+)
• How to put the same pattern in a child template or a club template
• What to put on the page (search, home, useful links)
• How to test status codes, not only the design
• When to 301 instead of 404

Official module positions: Custom Error Pages (Joomla 5.4 manual). Magazine walkthrough: The 404 That Could (JCM, November 2025).

The 2019 method, and why to stop using it

The old Infyways steps were: create a 404 article, noindex it, copy error.php, then:

header('Location: /index.php?option=com_content&view=article&id=292');
exit;

Search engines need 404 (or 410) for URLs that are gone with no replacement. Soft 404s (200 with “not found” text) waste crawl time. If the URL moved, use a 301 in System → Redirects, not a custom error page.

If your site still has that Location block in error.php, delete it before you add a module. Put the file in a child so the next Cassiopeia update does not restore a hack, and so your fix is not wiped. Rule: customize Joomla without editing core.

Joomla 5 and 6: the error-404 module (preferred)

Cassiopeia since Joomla 5.0 reads modules in:

• error-404 for not found
• error-403 for forbidden

If no module is published there, visitors still get the default language strings. Debug output still appears under the module when debug is on.

No error.php edit is required on stock Cassiopeia 5+. A child still needs the same include if you copied a thin error.php.

Step 1: Use a child template

Create and assign a Cassiopeia child if you do not have one. How to set up a Joomla child template.

Club templates: check whether they already declare error-404. If not, you will add the include in Step 4.

Step 2: Create the 404 content as a module

1. Content → Site Modules → New
2. Type: Custom (Custom HTML). Search, Latest Articles, or a menu module also work.
3. Title: something you can find later, for example 404 message. You can hide the title.
4. Write the message: short apology, home link, search, two or three real destinations. Keep it useful, not a joke that hides the next click.
5. Position: type error-404 if it is not in the dropdown. Cassiopeia 5+ accepts it even when the style UI is thin.
6. Status: Published. Menu assignment: On all pages. The error document is not a normal menu item. All pages is the safe assignment.
7. Save.

Use absolute https:// URLs for images and the home link. Relative src="images/…" often breaks on nested missing paths (/category/no-such-page). That is a known error-page path issue. Prefer full URLs until your Joomla patch level includes the error-page SEF fixes.

Step 3: Test the status, then the design

Open a URL that does not exist, for example https://www.example.com/this-page-is-not-real.

You should see your module. Then check the status:

• Browser Network tab, or
• curl.exe -sI https://www.example.com/this-page-is-not-real

You want HTTP/1.1 404 (or 404 from HTTP/2). If you see 200 or 302 to /404 or to an article, you still have a redirect in error.php or in .htaccess.

Step 4: Joomla 4, or a template without error-404

Copy parent error.php into the child (same filename at the child template root), then add the official include. Do not edit the parent Cassiopeia file.

<?php
$errorCode = $this->error->getCode();
?>
<?php if ($this->countModules('error-' . $errorCode)) : ?>
  <div class="container">
    <jdoc:include type="modules" name="error-<?php echo $errorCode; ?>" style="none" />
  </div>
<?php else : ?>
  <?php // keep the template's original default message here ?>
<?php endif; ?>

That snippet is the Joomla custom error pages pattern. Wrap it around the default heading so you do not delete fallback text.

A full branded layout is still error.php in the child: logo, user.css, maybe a search module. Same child rule as any other PHP file.

Step 5: 403, Redirects, and language strings

Do not noindex a real 404 URL in an article. There should not be a public article acting as the 404 document.

Key takeaways

1. A custom 404 page must keep HTTP 404. Do not redirect error.php to a com_content article.
2. On Joomla 5 and 6 Cassiopeia, publish a module in error-404.
3. Put PHP and CSS in a child template. Parent updates will replace error.php if you edited Cassiopeia itself.
4. Use absolute URLs for images and home on the error document.
5. Test with a fake path and with the response code.
6. Moved content is a 301. Gone content is a 404. Soft 200 is the worst of both.

Need a branded error page built into a client template? Joomla design services. Ongoing 404 cleanup: Joomla SEO services.

Frequently asked questions

How do I create a custom 404 page in Joomla 5?

Publish a Custom HTML module in the error-404 position on Cassiopeia (or a child that includes that position). Visit a missing URL and confirm HTTP 404.

Should a Joomla 404 page return HTTP 200?

No. 200 on a not-found URL is a soft 404. Keep 404. Redirects belong in the Redirect component when the page moved.

Does the error-404 module work on Joomla 4?

Not in core Cassiopeia 4. Copy error.php into a child and add the error-{code} module include, or run Joomla 5+ Cassiopeia.

Why are images broken on some 404 URLs?

The missing path is nested, and the image used a relative URL. Use absolute https:// links. Update Joomla when error-page SEF path fixes are in your branch.

Can I use an article as the 404 page?

You can, if you redirect to it. You should not. You lose a clean 404. Use a module on the error document instead.

Will a Cassiopeia update delete my 404 module?

No. Modules live in the database. A parent error.php you edited by hand can be overwritten. Keep PHP in a child.

Updated 15 October 2026 · By Abhilash Sahoo, Founder, Infyways

Every result below was tested on a real Joomla 5.4.10 site (PHP 8.2) and a Joomla 6.2.0 site (PHP 8.4) running on our own machine — the status codes, headers and screenshots are the actual output, not documentation copy. If you’d rather hand ongoing upkeep to a team, we run Joomla support and maintenance plans, but you don’t need us to flip the switch — this guide covers it.

How do I turn on maintenance mode in Joomla?

1. Log in to your Joomla administrator at yoursite.com/administrator/.
2. Open System → Global Configuration (the Site tab).
3. Set Site Offline to Yes.
4. Under Offline Message, choose Use Custom Message and type what visitors should see, or pick the site’s default.
5. Optionally set an Offline Image (your logo).
6. Click Save. The site is now offline for the public.

That’s the whole task. Everything else on this page is about doing it well — keeping your SEO intact, branding the page, and not locking yourself out.

What do visitors actually see?

Guests get the template’s offline.php layout — in the default Cassiopeia template that’s a centred card with your message, your offline image, and a login form. The login form is there on purpose: it’s how you (a Super User) get back into the live site without touching the admin. The page is rendered by Joomla, so it still carries your template’s styling.

Does maintenance mode return the right HTTP status for SEO?

Yes. We requested the offline front page with curl -I and Joomla returned:

HTTP/1.1 503 Service Unavailable
Content-Type: text/html; charset=utf-8

503 is exactly what you want. It tells search engines “the site is temporarily down, come back later” so they keep the URL in the index rather than dropping it. A page that returned 200 (normal) with a “we’re offline” body would risk Google indexing the offline notice; a 404 or 403 would risk losing rankings. Joomla sets the status in core — in SiteApplication::render() it calls setHeader('Status', '503 Service Temporarily Unavailable') whenever the site is offline and the visitor isn’t an authorised user.

The one thing Joomla doesn’t send is a Retry-After header. That header is optional and Google treats a 503 correctly without it, but if you want to hint when you’ll be back, you can add it — see the override section below.

Who can still use the site while it’s offline?

We tested each type of request against the offline Joomla 5.4 site:

So you can keep working on the front end while the public is held out. Access is controlled by the core.login.offline permission — by default only Super Users have it, but you can grant it to a group (e.g. a client’s reviewer) in Global Configuration → Permissions so they can preview the site while it’s offline.

What does the Site Offline toggle write to configuration.php?

The toggle just edits plain PHP variables in your site’s configuration.php:

public $offline = true;
public $offline_message = 'This site is down for maintenance.<br>Please check back again soon.';
public $display_offline_message = 1;   // 0 = none, 1 = custom message
public $offline_image = '';

This matters for the most common emergency: if you ever can’t log in on the offline page, you don’t need the admin at all. Open configuration.php over SFTP or your host’s file manager, change $offline = true; to $offline = false;, save, and the site is back. (More on that in the lockout section.)

How do I brand the offline page or add a Retry-After header?

For a simple logo + message, the Offline Image and Offline Message fields are enough. For a fully custom page, override the template’s offline.php. In Cassiopeia the file is templates/cassiopeia/offline.php; copy it into your child template and edit it there so an update won’t overwrite your work. (If a template has no offline.php, Joomla falls back to templates/system/offline.php.)

Because the override is a normal PHP file, you can also set a Retry-After header from it. We tested this on the real site — adding one line produced the header:

<?php
http_response_code(503);
header('Retry-After: 3600');   // tell crawlers: try again in 1 hour
?>

Result:

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

You can do the same at the server level in your .htaccess file if you prefer a maintenance page that bypasses Joomla entirely (useful during an upgrade when Joomla itself is being replaced).

Is this the same in Joomla 6.2?

Yes. We installed a clean Joomla 6.2.0 (the latest version) on PHP 8.4 and ran the same tests: the Site Offline toggle lives in the same place, guests get a 503, the admin stays on 200, and the offline page behaves identically. The only platform note is that Joomla 6.x requires PHP 8.3 or newer (Joomla 5 runs on PHP 8.1+), so a very old server may need a PHP bump before you upgrade. If you’re planning that move, our Joomla migration guide covers doing it without downtime.

Maintenance mode vs. a real upgrade or migration

Joomla’s offline switch is for short interruptions — pushing content, swapping a template, a quick extension update. It is not a backup or a staging environment. Before any risky change:

• Take a full Joomla backup (files + database) first.
• For bigger work, do it on a staging copy and only flip the live site offline for the final cut-over.
• If you’re changing the template or layout, use overrides instead of editing core so updates don’t undo your changes.

Troubleshooting: common maintenance-mode problems

Help, I locked myself out

This is the one that scares people, and it’s genuinely a 60-second fix. Maintenance mode never touches your database, so you can always undo it from the files:

1. Connect over SFTP, SSH, or open your host’s file manager (cPanel, Hostinger, Plesk).
2. Open configuration.php in the site root.
3. Change public $offline = true; to public $offline = false; and save.
4. Delete the contents of cache/ and administrator/cache/.

The site is back instantly. There’s no database flag and no “maintenance table” to repair — a relief if you’ve just come from cleaning up a hacked Joomla site, where offline mode is step one of containment.

Frequently asked questions

Does Joomla maintenance mode hurt my SEO?

No, as long as it’s temporary. The offline page returns HTTP 503, which tells search engines the downtime is temporary and keeps your URLs indexed. Problems only appear if a site stays on 503 for weeks — then Google may start treating it as gone.

What status code does Joomla’s offline mode return?

503 Service Unavailable, set in core. We confirmed it with curl -I on both Joomla 5.4 and 6.2. The admin area and logged-in Super Users still get 200.

Does Joomla send a Retry-After header?

No, not by default. Google handles 503 correctly without it, but you can add one via a custom offline.php override or an .htaccess rule if you want to hint a return time.

Can I still log in while the site is offline?

Yes. The offline page itself has a login form. Super Users (and any group you grant the core.login.offline permission) can log in there and browse the live site; everyone else sees the offline page. The /administrator/ login also works normally.

Where is the maintenance-mode setting in Joomla?

System → Global Configuration → Site tab → Site Offline. It’s the same location in Joomla 4, 5 and 6.2.

Can I customise the offline page?

Yes. Set an offline message and image in Global Configuration for a quick change, or override templates/<your-template>/offline.php (fallback templates/system/offline.php) for full control, ideally in a child template.

Will my REST API still work during maintenance mode?

No. We tested the API endpoint and it returned 401 while the site was offline, so integrations that rely on the public API will pause until you’re back online.

How do I take the site offline for a full Joomla upgrade?

During a core upgrade Joomla is mid-replacement and can’t reliably serve its own offline page, so use a server-level maintenance page via .htaccess instead, and always take a full backup first.

Does maintenance mode block logged-in registered users?

By default yes — only Super Users bypass it. If you want a specific group (e.g. client reviewers) to see the site while it’s offline, grant that group the “Offline Access” (core.login.offline) permission in Global Configuration → Permissions.

Is there a plugin for scheduled maintenance windows?

Joomla’s built-in toggle is manual. If you want unattended, scheduled maintenance — updates, backups, security monitoring handled for you — that’s exactly what our Joomla support and maintenance service does.

To add a favicon in Joomla, change what the active site template (or a system plugin) prints in the page head as rel="icon". That is not always Cassiopeia, and it is not always three Joomla-named files. Helix, T4, Gantry, YOOtheme, and most club templates have their own favicon field or their own filenames. Cassiopeia is only the core default. View source, find the current href, then use that template’s option, replace that file, or inject a pack and strip the old tags.

A favicon is the mark in the browser tab, bookmarks, and (with extra sizes) on a phone home screen. Joomla 4, 5, and 6 all work the same way at the HTTP level: whatever is in <head> wins. This guide starts with that, then covers template options, Cassiopeia’s media files as one special case, cache, and when a generator plugin is easier than fighting five different template UIs.

The tab shows whatever the assigned template or a plugin put in the head. Cassiopeia is one of those templates, not the only one.

What you will learn

• How to see which URL Joomla is actually using for the icon
• Where commercial templates usually store the favicon (style options)
• The Cassiopeia-only three-file names, if that is your template
• Why Atum (administrator) is a separate pack
• How cache hides a correct upload
• When Easy Favicon is the template-agnostic manager

Do not edit parent index.php to hard-code a <link>. Same rule as CSS: customize Joomla without editing core. Prefer a child template when you must change files.

Step 1: See what is in the head

Open the public site. View source. Search for rel="icon", apple-touch-icon, and shortcut icon.

Write down:

• The href (that is the file you must replace, or the tag you must override)
• Whether there is more than one icon link (SVG plus ICO plus Apple is normal)
• Whether the path is media/templates/…, templates/…, images/…, or a CDN

If Helix (or another club template) prints a tag after Cassiopeia’s, the later tag often wins in the browser. Replacing Cassiopeia files then looks like “Joomla ignored me.” You were on the wrong template.

Also check System → Site Template Styles. The style with the star (and any menu assignment) is the one that must receive the change.

Step 2: Use the template’s own favicon control

Most paid templates never use joomla-favicon.svg. They expect an upload in Template Styles.

Upload a square PNG or ICO, 512×512 or larger if the field accepts PNG. Save the style. Then skip to cache (Step 4) and prove the new href in view source.

If the field only stores one ICO, you still will not get Apple 180 or Android adaptive icons unless the template generates them. That gap is why a pack plugin exists.

Step 3: Replace files only when the head points at files

This is the right move when view source shows a path under your template’s images or media folder.

Cassiopeia (and a Cassiopeia child) is the documented core case. It loads three names:

• joomla-favicon.svg (rel="icon")
• favicon.ico (rel="alternate icon")
• joomla-favicon-pinned.svg (rel="mask-icon")

Path on Joomla 4.1, 5, and 6:

media/templates/site/{template}/images/

If the assigned style is a child cassiopeia_brand, that folder is media/templates/site/cassiopeia_brand/images/. Replacing files only on parent Cassiopeia does nothing while the child is default.

If you replace only favicon.ico, Chrome can keep the SVG. Replace all three. Official map: Cassiopeia Template Folders and Files.

Any other template: do not invent those three Joomla filenames. Replace the file the href already names, or use the template option in Step 2. Joomla 4.0-era templates/{name}/images/ still appears on old forks. Match the live href, not a blog from 2017.

Root /favicon.ico: some bots still request it. It does not override a later SVG in Chrome.

Wrong template style, or the wrong filename, is why the Joomla mark remains.

Step 4: Clear cache and test in a clean browser

1. System → Maintenance → Clear Cache
2. Purge CDN cache if you use one
3. Private window, or a browser profile that has not seen the old icon

Chrome on phones caches favicons hard. View source again. The href must change. If it did not, you edited the wrong style or the template is still injecting the old URL.

Pick the method

Managing icons across templates with Easy Favicon

Template options and Cassiopeia files are enough when you have one ICO and a cooperative theme. They are a poor manager when every client site uses a different template, or when Helix keeps printing the old apple-touch link.

Easy Favicon is a JoomlaX system plugin for Joomla 4, 5, and 6. It is template-agnostic: one master image, generate the pack, inject tags, optionally strip competing favicon and apple-touch tags so Helix, T4, or Cassiopeia defaults lose. That is the point of mentioning it here. It is not required to “add a favicon.”

From System → Plugins → System – Easy Favicon you can manage:

PHP 8.1+, GD or Imagick. No jQuery. Icons stay on your server.

First run: install the inner plugin zip, enable it, choose a square master (512×512+ PNG or SVG), Generate all icons, clear cache, check the public tab, then the admin tab if the admin pack is on. If generate fails, check GD/Imagick. If the old icon remains, raise strip strength and purge CDN. If a PWA extension owns the manifest, set Defer or Off.

Docs: Easy Favicon documentation. Demo: Easy Favicon demo. JED listing. JoomlaX is Infyways’ extension store.

Key takeaways

1. The favicon is whatever the assigned template or plugin puts in <head>. Start with view source.
2. Most commercial templates use a style option, not Cassiopeia’s three filenames.
3. Cassiopeia is the core default: joomla-favicon.svg, favicon.ico, joomla-favicon-pinned.svg in that template’s media images/ folder, preferably a child.
4. Atum (admin) is a second template. Frontend files do not change the backend tab.
5. Prove the new href, then fight cache.
6. A pack plugin is for multi-size, admin, dark mode, and stripping template tags, not for every simple ICO swap.

Client branding across club templates: Joomla design services.

Frequently asked questions

How do I add a favicon in Joomla 5 or 6?

Find the assigned template style. Use its favicon option if it has one. On Cassiopeia, upload the three named files to that template’s media images/ folder. Clear cache and check view source.

Does this only work with Cassiopeia?

No. Cassiopeia is the core default and uses three specific filenames. Most live sites use Helix, T4, Gantry, YOOtheme, or another club template. Start from view source and that template’s style options.

Why does Chrome still show the old icon?

Wrong template style, a later tag from a club template, only one of several files replaced, or favicon cache. View source before you upload again.

Do I need a plugin?

No, if the template option or file replace already updates rel="icon". Yes, if you need a full size pack, a separate admin icon, or to strip Helix (or similar) tags.

Where do Easy Favicon files live?

Under images/easyfavicon/. The plugin injects head tags. You do not have to name Cassiopeia’s three files when it is managing the pack.

Will a template update delete my favicon?

A parent template media file can come back. A child, a template-style upload in the database, or plugin files under images/easyfavicon/ are safer.

To customize Joomla without editing core files, put every change in a layer Joomla will not overwrite: a child template, user.css / user.js, a layout override in html/, a language override, a template style, or a custom plugin. Do not edit files under components/, modules/, plugins/, libraries/, or the parent template. Those paths come back to stock on the next Joomla, PHP, or extension update. This holds on Joomla 4.1+, 5.4, and 6. On Joomla 3 there is no Create Child Template button. You still use html/ overrides and language overrides. You do not patch core there either.

Editing Cassiopeia, com_content, or a plugin “just this once” is how sites get stuck on old Joomla. The safe stack is smaller than it looks. Pick the smallest tool that matches the job, keep the parent stock, and check overrides after every update.

Updates replace core and the parent template. Your child, language overrides, and custom plugins stay.

What you will learn

• What counts as a core file (and what does not)
• Which Joomla tool to use for CSS, HTML, wording, and behaviour
• How to set up a child template so CSS and overrides survive updates
• Where user.css actually lives on Cassiopeia
• How Create Overrides copies layouts into html/
• When a language override or a custom plugin is the real fix
• What to re-check after a Joomla update

The problem core edits create

You change one PHP file. The header looks right. Two weeks later Joomla ships a security release. The updater replaces that file. The header is stock again. Or worse: the update skips the file because it differs from the package, and you sit on an unpatched copy.

That is not a discipline problem. It is how Joomla packages work. Core and most extension files are owned by the installer. Template styles (logo, colour params, menu assignment) live in the database and survive. Files you typed into components/com_content/ do not.

The fix is not “remember to re-apply the hack.” The fix is never putting the hack in a path the installer owns.

Official layout override model: Layout Overrides in Joomla. Child templates: Joomla User Manual, Child Templates. Cassiopeia user.css: Cassiopeia Template Customisation.

What counts as a core file

Treat these as do not edit:

These are safe homes when you use them as designed:

A duplicate of the whole Cassiopeia folder renamed “Cassiopeia custom” is not a child. It is a fork. You now maintain hundreds of files you did not write, and Cassiopeia security fixes never reach it.

Pick the smallest safe tool

If CSS can do it, stop. If the string is a language key, do not override PHP to change a label.

The rest of this article is the order of operations. The child-template post is the click-by-click for Create Child Template. Use that when you reach Step 2. Do not skip it and drop user.css into the parent “for now.”

Step 1: Name the change before you open a file

Write one sentence: “I need the article byline stacked, not inline,” or “I need the header background #0b3d5c,” or “I need Read more to say Continue.”

Then classify it:

1. Look only (colour, type, hide): CSS.
2. Markup (extra wrapper, different heading level, remove a div): layout override.
3. Wording: language override. Confirm with Debug Language if you are unsure which key it is.
4. Data: custom field, not a new column in #__content by hand.
5. Logic: plugin. If you cannot name the event (onContentPrepare, onAfterRoute), you are not ready to write PHP.

If you cannot classify it, you are about to edit the wrong file.

Step 2: Create a child template (Joomla 4.1 and later)

On Joomla 4.1, 5, and 6, open System → Templates → Site Templates, open an inheritable parent (Cassiopeia is the one that ships ready), and click Create Child Template. Assign the child’s style as default or per menu item.

Full clicks, media/ vs templates/, Atum, and making a custom parent inheritable: How to set up a Joomla child template.

Until that style is assigned, the public site still uses the parent. Creating the child does not change the frontend by itself.

Joomla 3: there is no native child. Keep overrides in your template html/ folder. Prefer a template you control, not a club template you will overwrite on the next vendor zip. Plan the Joomla 3 to 6 upgrade so you can use children.

Joomla 6: Cassiopeia Extended is already a child of Cassiopeia. Do not hack Extended as if it were a parent. Copy the child (6.1) or create your own child of Cassiopeia.

Do these in order. CSS first. PHP last.

Step 3: Put CSS in user.css (not in the compiled sheet)

Cassiopeia loads user.css if the file exists. On Joomla 4.1 and later the path is:

media/templates/site/{template}/css/user.css

For a child named cassiopeia_brand, that is media/templates/site/cassiopeia_brand/css/user.css, not the parent’s file. A child does not load the parent’s user.css. If you already wrote rules in Cassiopeia and then created a child, copy them into the child’s file or the site will look stock.

In Template Manager: open the template, select the css folder, New File, name user (no suffix), type .css.

The Joomla 4.0-only path templates/cassiopeia/css/user.css was moved into media/ when child templates landed. If your CSS “does nothing,” you are almost always in the old folder, or you assigned a child while the file still sits on the parent. The next article in this series is the CSS-not-showing checklist. Until then, use the child-template user.css section.

Keep !important rare. Cassiopeia registers user.css with a high asset weight so it loads after the template sheet.

Step 4: Override HTML with Create Overrides

For component and module layouts:

1. System → Templates → Site Templates → {your child} → Create Overrides
2. Pick the component view or module.
3. Joomla copies the file into templates/{child}/html/…
4. Edit that copy only.

Filename rules matter. A copy named _default.php or a typo in the folder (com_content/article vs com_content/articles) means Joomla never loads it. Create Overrides is there so the path is correct.

Plugin layouts usually do not appear in that list. You copy tmpl by hand into html/plg_{group}_{element}/. Details: plugin overrides in the html folder.

After a Joomla update, open the template’s Overrides (or Updated Files) list. If core changed a layout you overrode, diff your copy. Joomla documents this as override management. It does not watch user.css or user.js. You review those yourself.

🔗 Layout Overrides in Joomla
Folder map for components, modules, plugins, and JLayouts.

Step 5: Change wording with a language override

If the public string exists in a .ini language file, System → Language Overrides. Site vs Administrator is a different list. Debug Language shows the constant on the page.

Do not override default.php to change “Read more.” That is a core-edit habit with extra steps.

Setup: Joomla language overrides.

Step 6: Add data with custom fields, not a core hack

Price, subtitle, event date, and spec tables belong in Content → Fields. Automatic display or a field layout in the child. If you still run K2 extra fields, migrate on Joomla 3 first: K2 to com_content.

Fields how-to: Joomla custom fields.

Step 7: Change behaviour with an extension you own

Redirect rules, extra authentication, “hide this module when…” that CSS cannot express: write or install a plugin. Leave plugins/system/sef and libraries/src alone.

If an installed extension is broken, do not patch its PHP on the server. Duplicate the plugin with a new element name, or wait for the vendor, or replace it. A patched third-party file is the same class of problem as a patched core file.

Need a plugin built to spec? Joomla plugin development.

After every Joomla or template update

1. Clear Joomla cache and your browser cache.
2. Open the child template Overrides list. Diff any layout Joomla marked as updated.
3. Skim user.css for selectors that no longer exist (Cassiopeia class names do change between major versions).
4. Confirm the child style is still default or still assigned to the right menus.
5. If you use a club parent, read the vendor notes before you copy their new index.php over your child copy.

This five-minute pass is cheaper than discovering a blank header on Monday.

What this does not replace

A child template is not a page builder, a CDN, or a backup. It does not fix PHP 8 fatals from an old extension. It does not make a commercial template inheritable until the vendor sets <inheritable>1</inheritable> and moves CSS under media/.

Safely customize Joomla without editing core files means you still test on staging. Overrides can be wrong. CSS can hide the cart button. The rule is only: when it is wrong, the stock parent is still there to compare against.

Key takeaways

1. Never edit components/, modules/, plugins/, libraries/, or the parent template to “make it look right.”
2. Classify the job: CSS, HTML, string, data, or behaviour. Use one tool.
3. On Joomla 4.1+, create a child, assign its style, then add files.
4. Cassiopeia custom CSS belongs in media/templates/site/{template}/css/user.css on the active template.
5. Layout overrides live in the child’s html/ folder. Create Overrides for components and modules. Plugin tmpl is usually manual.
6. Labels go through language overrides. Extra article data goes through custom fields.
7. After updates, diff overridden PHP. Review user.css yourself. Joomla will not do that for you.

If the next problem is “I did all this and the CSS still does not load,” that is the 4 September post in this series. If the override PHP does not run, that is the 11 September post.

Need a template customized without forking core on a client site? Joomla design services.

Related Joomla troubleshooting

• Joomla CSS changes not showing
• Joomla JavaScript not working
• Template override not working
• Template override disappeared after an update
• Joomla module not showing
• Custom fields not showing

Frequently asked questions

Can I customize Joomla without editing core files?

Yes. Use a child template, user.css, layout overrides in html/, language overrides, custom fields, and custom plugins. Leave core and parent template files stock.

Is editing Cassiopeia the same as a child template?

No. Cassiopeia is the parent package. Updates replace it. A child stores only your files. Setup: Joomla child template.

Where do I put custom CSS in Joomla 5?

For Cassiopeia, media/templates/site/cassiopeia/css/user.css, or the same path under your child name. Create the file if it is missing. The old templates/cassiopeia/css/ location is the Joomla 4.0-era path.

Do template overrides survive a Joomla update?

Overrides in a child (or in a template Joomla does not overwrite) stay on disk. The source layout in components/ may change. Diff your copy after the update. CSS is not in that checker.

Can I edit a plugin file if I back it up?

You can. The next extension update still overwrites it, or the updater skips it and you stay unpatched. Use an html/plg_… override when there is a tmpl, or a plugin you own when you need logic.

What about Joomla 3?

No native child template. Use html/ overrides and language overrides on a template you control. Do not patch components/. Move to 4.1+ when you can so children exist.

Is a template style enough?

For logo, colour parameters, and menu assignment, yes. For PHP, CSS files, and overrides, you need a child (or a template you fully own). A style still points at the same files.

A Joomla plugin override is a copy of a plugin layout file in your template html folder. The path is templates/{template}/html/plg_{group}_{element}/{layout}.php. It works on Joomla 4, 5.4, and 6 for any plugin group (system, content, fields, user, authentication, editors-xtd) if that plugin loads a layout through PluginHelper::getLayoutPath(). That almost always means a tmpl folder. No tmpl means there is nothing for html/ to replace. Most system plugins have no layout. A few that print HTML do.

This is the 2026 operator guide. It is not limited to page navigation. You will test for a layout, name the folder, put the file in a child template, and know when CSS or a language override is the real fix.

The plugin keeps the logic. Your template keeps the HTML. Updates replace the plugin. Your copy stays if it lives in a child.

What you will learn

• How plugin overrides differ from component and module overrides
• The tmpl test that decides yes or no, including system plugins
• The exact html/plg_{group}_{element}/ folder name
• Why Create Overrides in the template manager usually hides plugins
• How to override content page navigation, content vote, and field types
• What a plugin override can change, and what it cannot
• When to use html/layouts/ instead of html/plg_…
• How to debug an override that “does nothing”

The problem plugin overrides solve

You want Prev/Next as buttons. You want the vote stars in a different order. You want a field type to print a badge instead of a definition list.

The HTML lives inside the plugin, not in com_content’s article layout. Editing plugins/content/pagenavigation/tmpl/default.php works until the next Joomla or extension update puts the stock file back.

A component override of the article view does not catch output the plugin injects later. A module override does not catch it either. You need a plugin override, or you are hacking core.

Official path and the tmpl rule: Layout Overrides in Joomla. The J4 layout page shows the same idea for vote: Template Layouts.

Three kinds of output, three folders

Create Overrides under System → Site Templates → {template} → Create Overrides lists components, modules, and many JLayouts. It usually does not list plugins. You create html/plg_… by hand. That is why people think plugin overrides do not exist.

The tmpl test (including system plugins)

System is not a special exception. The test is the same for every group.

1. Open plugins/{group}/{element}/.
2. If you see tmpl/ with .php files, a template override is possible if the PHP calls PluginHelper::getLayoutPath('{group}', '{element}', '{layout}') (or the CMS plugin helper equivalent).
3. If there is no tmpl and no JLayout render, stop. html/plg_system_cache/ will never run. Cache, SEF, Redirect, Language Filter, Remember Me, and most authentication plugins have no frontend layout.
4. Optional confirmation: search the plugin PHP for getLayoutPath. If HTML is concatenated in the event method (return '<div>…'), the author did not make it overridable. Fork the plugin or ask the vendor. Do not patch core.

Developer note: the helper is JoomlaCMSPluginPluginHelper::getLayoutPath($type, $name, $layout = 'default'). The third argument is the file name without .php.

What you can do, and what you cannot

An override only replaces markup the plugin already prints through a layout. It does not become a second plugin. If the job is behaviour, routing, or a string, use a different Joomla tool.

What you can do

What you cannot do

Joomla does not scan html/plg_* for every plugin. It only looks there when the plugin calls getLayoutPath() (or a JLayout helper) to include a file. If that call never happens, your copy is never loaded. That is the whole “why” for most of the rows below.

The pattern is the same every time: no layout lookup, no override. Group system is not a lock and not a key. Only the PHP that includes a file is.

How to name the html folder

templates/{template}/html/plg_{group}_{element}/{layout}.php

{group} is the first directory under plugins/ (system, content, fields, user, …). {element} is the plugin folder name (the element in the XML). Underscores in the plugin name stay. Prefix is always plg_.

Same formula. Different group name. The Create Overrides tab still may not show them.

Wrong folder names that fail silently:

• html/pagenavigation/ (missing plg_content_)
• html/plugins/system/example/ (that is not how Joomla looks up plugin layouts)
• html/plg_system_example/tmpl/default.php (no extra tmpl under html)

Site overrides go in the site template. Administrator plugin UI (if any) goes in an administrator template such as a child of Atum: administrator/templates/{atum_child}/html/plg_….

Put the file in a child template

Copying into Cassiopeia’s html/ works until Cassiopeia updates. Create a child first, assign its style, then add html/plg_… there. Setup: How to set up a Joomla child template.

A template style does not store PHP. Only the template folder does.

Step 1: Confirm the plugin is overridable

1. System → Plugins. Note Type (group) and Element (folder name).
2. On disk: plugins/{type}/{element}/tmpl/.
3. Open the main plugin class. Confirm getLayoutPath.
4. Note every layout file (default.php, vote.php, rating.php). You override only the files you copy. Missing files still load from the plugin.

Backup the site. An override with a PHP error blanks the page that loads that plugin.

Step 2: Create the html folder

On the active template (the child):

templates/{your_child}/html/plg_{type}_{element}/

Example for page navigation:

templates/cassiopeia_site/html/plg_content_pagenavigation/

FTP, hosting file manager, or System → Site Templates → {child} → html (create folder if the UI allows). The template manager will not invent plg_content_pagenavigation for you.

Manual folder. Then copy. Then cache. The public page does not change until the active template is the one that contains the file.

Step 3: Copy the layout and edit HTML only

Copy plugins/{type}/{element}/tmpl/{layout}.php into that folder. Same file name.

Change markup, CSS classes, wrapping. Keep the PHP that reads $displayData or the variables the plugin set up. If you drop a required variable, the layout fatals.

Do not copy the plugin class, XML, or language files into html/. Those are not overrides.

Step 4: Clear cache and prove the file is used

1. Assign the child template style to the menu item (or as default).
2. System → Clear Cache (and any page-cache plugin).
3. Add a harmless HTML comment or class in the override. View source. If it is missing, Joomla is not loading that file.

Then style for real.

Worked example: page navigation

Core plugin Content – Page Navigation. Group content, element pagenavigation.

Enable the plugin. In the article Options (or menu item), show page navigation. Edit the override to wrap links in your button classes. This is the example every old tutorial uses. It still works on Joomla 5 and 6.

Worked example: article vote

Core plugin Content – Vote. Layouts include vote.php and rating.php.

templates/{child}/html/plg_content_vote/vote.php
templates/{child}/html/plg_content_vote/rating.php

Copy both if you change both. Copy one if you only restyle the form or only the stars.

Worked example: a custom field type

Field plugins live in plugins/fields/{type}/tmpl/. Override:

templates/{child}/html/plg_fields_{type}/{layout}.php

That restyles every field of that type. It does not restyle one field id. For one field, Automatic Display, {field ID}, or an article override is the custom fields path. For “Read more” text, use a language override, not a plugin layout.

System plugins: when html/ works

A system plugin that only listens (onAfterRender, onAfterRoute, headers, redirects) has no layout. Creating html/plg_system_redirect/ does nothing. Redirect rules stay in com_redirect.

A system plugin that prints a box, bar, or consent UI and ships tmpl/ uses the same formula:

plugins/system/{element}/tmpl/default.php
→ templates/{child}/html/plg_system_{element}/default.php

Third-party docs that show html/plg_system_mcnsystem/ are using this rule. Your vendor’s element name replaces theirs.

Debug, privacy consent, guided tours, and similar core tools may use tmpl or JLayout. Check the disk. Do not assume every system plugin in Joomla 6 gained a layout. Most still have none.

JLayout is a different folder

If the plugin (or core) calls LayoutHelper::render('joomla.content.…') or a namespaced layout, the override is:

templates/{child}/html/layouts/joomla/…

or the same tree the layout name implies under html/layouts/.

Do not put a JLayout file in html/plg_content_vote/ unless that is actually how getLayoutPath resolves it. Mixing the two folders is the usual “I copied it and nothing changed” bug after tmpl exists.

The Create Overrides tab does list many layouts/joomla files. Use it for those. Use a manual plg_ folder for plugin tmpl files.

Alternative layouts

Modules and articles can have extra files without underscores, chosen in a dropdown. Plugins almost never expose that dropdown. A second file in tmpl/ is used only if PHP asks for that layout name. For plugins, you normally override default (or vote / rating) in place. You do not get a “use my layout on this menu item” switch unless the plugin author coded one.

What a plugin override is not

Use the tables above. Short version: markup in a layout, yes. Events, routing, one-off pages, and language strings, no.

Troubleshooting

After every extension update, diff override vs new tmpl. Plugin overrides are not merged automatically.

Key takeaways

1. Plugin overrides are real on Joomla 4, 5, and 6. They are usually manual.
2. Folder: html/plg_{group}_{element}/{layout}.php.
3. tmpl plus getLayoutPath means yes. No layout means no, including most system plugins.
4. You can change markup, classes, and field-type HTML. You cannot change plugin events, SEF, cache, or one article only.
5. System plugins that print HTML and ship tmpl use html/plg_system_{element}/.
6. Content vote, page navigation, and field types are the core examples you will actually use.
7. JLayouts use html/layouts/, not html/plg_….
8. Store the file in a child template. Re-diff after updates.

Frequently asked questions

Can I override a system plugin in the html folder?

Yes, if that system plugin has a tmpl file loaded with getLayoutPath. No, if it only hooks events and never includes a layout. The group name system does not block overrides and does not magically enable them.

Why is my plugin missing from Create Overrides?

Joomla’s override UI is built around component views, modules, and many layouts. Plugin tmpl files are often omitted. Create html/plg_{group}_{element}/ yourself.

Does this work the same on Joomla 5 and Joomla 6?

Yes. The helper and folder formula did not change. More core plugins may ship tmpl than in Joomla 3. Always check the folder on disk. Do not trust a wiki sentence that says only page navigation is overridable.

Can I override only one article’s page navigation?

Not with a plugin override. The override applies everywhere that plugin layout runs. For one page, CSS, a module, or a different article layout is the usual workaround.

Should I edit the plugin PHP instead?

No. Updates wipe it. If there is no layout, write a small custom plugin or use parameters. If there is a layout, copy it into the child html/ folder.

Where do administrator plugin screens get overridden?

In the administrator template, typically a child of Atum: administrator/templates/{child}/html/plg_{group}_{element}/. Site html/ does not apply to the backend.

Conclusion

Plugin HTML is overridable. The Create Overrides tab just does not advertise it. Test for tmpl, name plg_{group}_{element}, put the file in a child, and leave system plugins without layouts alone.

If you are still editing Cassiopeia html/ directly, create the child first. If the text is a language string, override the string. If the extra data is a field, custom fields plus a field-type plugin override cover display.

Need this done on a client template? Joomla design services.

Joomla custom fields are core extra data on articles, contacts, and users. They live at Content → Fields (and Field Groups) on Joomla 4, 5.4, and 6. They replace K2 extra fields: typed inputs, groups as editor tabs, values stored per item, optional automatic display on the public page. You do not need K2, a CCK, or a page builder for price, author bio, event date, or a specification table. If you still run K2, copy extra fields into this system on Joomla 3 first. That pipeline is the companion guide: Migrate K2 to Joomla articles before you upgrade.

This article is the feature how-to. The K2 article is the migration sequence. Read both if you are leaving K2. Read only this one if you already use com_content and need structured data on articles.

K2 stored extra data on items. Joomla stores the same idea on native articles, with groups, category assignment, and display you control.

What you will learn

• How custom fields differ from K2 extra fields (and from article body HTML)
• Field vs field group vs category assignment
• How to create a group, a field, and a value on an article
• Automatic display vs {field} in the body vs a layout override
• What a K2 migration copies, and what you still set by hand
• When a child template is the right place to print fields

How this guide and the K2 guide split the work

Migrate K2 Pro (phase 2) creates field groups, fields, and values from published K2 extra fields. It does not choose Automatic Display, rebuild your K2 item layout, or invent {field} shortcodes in the article body. Those jobs stay here.

Why custom fields exist (and why they beat extra fields)

K2 extra fields existed because Joomla 1.5 and 2.5 articles were title, images, and HTML. Magazines needed “Source,” “Duration,” “Price,” “GPS.” K2 bolted that onto com_k2.

Joomla 3.7 added custom fields to core. Joomla 4, 5, and 6 kept and extended them. Tags, nested categories, and workflows also moved into core. K2 did not follow Joomla 4. Extra fields therefore have no future as a platform. Custom fields do.

Custom fields are not a second article. They are named, typed, filterable values attached to an item. The editor shows them on a Fields tab, or on a tab named after the field group. The public site can print them automatically, or you print them in an override.

Use a field when the value is structured (a number, a list, a date, a media file, a yes/no). Keep narrative in intro/full text. Do not paste a spec sheet into TinyMCE if you will sort, filter, or style it later.

🔗 Joomla Docs: Adding custom fields (J5)
Official entry points: Content → Fields, Field Groups, and the context dropdown (Article vs Category).

K2 extra fields vs Joomla custom fields

Types are close, not identical. Confirm list options and media paths after a migration. Do not change a field type after it already holds data.

Approximate type mapping (what operators actually meet):

If a migrated field looks wrong, do not flip Type on a live field with thousands of values. Create a new field, copy values if needed, and retire the old one.

Step 1: Create a field group

Groups are editor UX. They do not change the database value. They become tabs on the article form.

1. Content → Field Groups.
2. Set the context to Article (not Category, unless you are adding data to the category itself).
3. New. Title something editors will recognise: Specs, Source, Event.
4. Save.

No group means every field piles onto a single Fields tab. That is fine for two fields. It is miserable for twenty.

After a K2 migration, groups usually already exist. Rename titles for editors. Do not delete a group until you confirm no field still points at it.

Step 2: Create the field and assign categories

1. Content → Fields, context Article, New.
2. Title: what editors see.
3. Name: lowercase, no spaces. Used in overrides and {field} lookups. Set it once.
4. Type: pick before you save production data.
5. Field Group: the tab from Step 1.
6. Assigned Categories: All, or the categories that should show this field. Remember: All skips Uncategorised. If migrated K2 items landed in Uncategorised, assign that category explicitly or move the articles.
7. Required, default, filter: set now. Filter decides sanitisation (Text, Integer, HTML, Raw).
8. Save.

New articles show the field only after a category is chosen. That is normal. Joomla waits for the category so it can apply assignment.

Order: group (tab), field (type and name), category (where it appears), display (what visitors see).

Step 3: Choose how the public page prints the field

Automatic Display (on the field):

A whole field group renders as one block, in field order, in that position.

Use automatic display for simple “label: value” lines (source, duration, licence).

Use Do not automatically display plus:

• {field 12} (field ID) in the article body when placement must differ per article, or
• a layout override when every article in a category needs a spec table, cards, or schema markup.

Overrides belong in a child template, typically under html/layouts/com_fields/ or in the article default.php if you print $this->item field arrays yourself. Editing Cassiopeia core files will be wiped on update.

Automatic display is the fast path. Overrides are the design path. Shortcodes are the one-off path.

K2 item templates that loop extra fields do not run after you uninstall K2. If the magazine layout was a two-column spec grid, plan the override before you delete html/com_k2. The values will be in custom fields. The HTML will not.

Step 4: After a K2 migration, walk the fields once

If you used Migrate K2 Pro:

1. Content → Fields and Field Groups. Counts should match published K2 extra fields and groups.
2. Open five articles. Fields tab (or the group tab) must show values, not empty inputs.
3. Set Automatic Display on the fields you want visitors to see without an override. Migration does not guess your old K2 item chrome.
4. Fix category assignment. If a field vanished from the editor, the article category is not in the assigned list (Uncategorised is the usual trap).
5. Spot-check media fields. Paths should point at images/k2-migrated (or your configured base), not media/k2/.
6. Rebuild the public layout: automatic display, then override if the design is more than a label list.

Permissions: if an editor cannot see a field, check the field’s Access and Display When Read-Only. That is not a migration bug.

What custom fields are not

Key takeaways

1. Custom fields are core. They are the replacement for K2 extra fields on Joomla 4, 5, and 6.
2. Group = editor tab. Field = type, name, value. Category assignment = which articles show the input.
3. Default All categories does not include Uncategorised.
4. Automatic Display prints a block. {field ID} places one value in the body. Overrides print a designed layout.
5. Migrate K2 Pro copies groups, fields, and values. You still set display and rebuild K2 item chrome.
6. Do not change Type on a field that already has production values.
7. Put field layout PHP in a child template, not in the parent.

Frequently asked questions

Are Joomla custom fields the same as K2 extra fields?

Same job, different system. Both attach typed data to content. Custom fields are core, work on Joomla 5 and 6, and use category assignment plus Automatic Display. Extra fields die with K2.

Do I create fields before or after I migrate K2?

Let the migrator create them from published extra fields, then adjust display and assignment. Creating a parallel set by hand first causes duplicate names and empty values. Manual field setup is for sites that never used K2.

Why is the Fields tab missing on a new article?

No category is selected yet, or the field is not assigned to that category. Choose the category. Check assignment. Remember Uncategorised is outside All.

Can I show a field only in an override, not above the article?

Yes. Set Automatic Display to Do not automatically display, then print the field in a child-template layout.

Will custom fields survive a Joomla 5 or 6 upgrade?

Yes. They are com_fields. K2 extra fields will not, because K2 will not. That is why the K2 migration runs on Joomla 3.10 first.

Can I use custom fields on contacts or users too?

Yes. Those are different contexts (Contacts → Fields, Users → Fields). Article fields do not automatically appear on contact forms. Create fields in the context you need.

Conclusion

K2 extra fields were a product. Joomla custom fields are the CMS. Create groups, assign categories, then decide display. If the data still lives in K2, migrate to articles first, then come back to this page and finish Automatic Display and the article layout.

Need both the copy and the field UI done on a large magazine? Joomla K2 migration services.