How many Templates & layouts issues are in this guide?

This guide covers 16 catalog entries with before/after replacements.

Joomla Templates & layouts changes: Joomla 3 → 4, 5 and 6

16 issues in this guide

Templates are a visual and structural cut. This guide groups 16 entries: row-fluid span12, col-xs-12 img-responsive hidden-xs, offset2 hide element-invisible input-block-level, JLayout, JLayoutFile, JLayoutHelper, function pagination_item_active($item), ISIS / Hathor, Beez3, Protostar fork, and 6 more. The replacement pattern is Cassiopeia or Atum (preferably as a parent with a child for branding), LayoutHelper / FileLayout from Joomla\CMS\Layout, Bootstrap 5 utility classes instead of row-fluid / span* / col-xs-* / img-responsive / hidden-xs, and the split head document includes Joomla 4+ templates use. Pagination item functions move into joomla.pagination.link layouts. Do not force jquery.framework from the template index — declare assets properly in the Media and Web Asset Manager guide. Hop mix: 12 at Joomla 3 → 4; 1 at Joomla 4 → 5; 3 at Joomla 5 → 6. Most template and CSS entries fail on the Joomla 3 → 4 hop when the front end first boots Cassiopeia. Use each catalog entry below for the exact class or file to replace.

CSS-BS2-001

row-fluid span12

Bootstrap 2 markup (row-fluid / span*)

Joomla 3 templates (Protostar, Beez, club templates) used Bootstrap 2. Joomla 4/5/6 admin and Cassiopeia use Bootstrap 5. Old class names do nothing — the layout collapses into one column.

row-fluid span12 → Bootstrap 5: row + col-*

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Patch possible — review itCSS / Bootstrap

Symptoms people search

template layout broken after upgrade · everything in one column · module chrome looks like 2012 · row-fluid does nothing

Replace this code

Swap row-fluid span12 for Bootstrap 5: row + col-*.

Joomla 3

Remove or stop calling this

<div class="row-fluid">
  <div class="span8">...</div>
  <div class="span4">...</div>
</div>
<button class="btn btn-small pull-right">

Joomla 4 / 6

Use this instead

<div class="row">
  <div class="col-md-8">...</div>
  <div class="col-md-4">...</div>
</div>
<button class="btn btn-sm float-end">

How to fix it

1Replace row-fluid with row.
2Replace span1–span12 with col-md-* (or col-*).
3pull-left/right → float-start/end. hide → d-none. img-responsive → img-fluid. btn-small → btn-sm.
4hero-unit and well have no 1:1 class — use spacing utilities or a card.

Also known as

row-fluid · span1 · span2 · span3 · span4 · span5 · span6 · span7 · span8 · span9 · span10 · span11 · span12 · offset1 · offset2 · offset3 · offset4 · pull-left · pull-right · hero-unit · nav-collapse · btn-mini · btn-small · input-block-level · element-invisible · hide · show · Bootstrap 2 · float-start · float-end · visually-hidden · form-control

Scan a ZIP for this Ask Infyways to fix it

CSS-BS3-001

col-xs-12 img-responsive hidden-xs

Bootstrap 3 leftovers

Some Joomla 3 club templates mixed Bootstrap 3. Those class names are not in Bootstrap 5.

col-xs-12 img-responsive hidden-xs → Bootstrap 5: col-*, img-fluid, d-none d-sm-block

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Patch possible — review itCSS / Bootstrap

Symptoms people search

responsive breakpoints wrong · images overflow

Replace this code

Swap col-xs-12 img-responsive hidden-xs for Bootstrap 5: col-*, img-fluid, d-none d-sm-block.

Joomla 3

Remove or stop calling this

<div class="col-xs-12 hidden-xs">
<img class="img-responsive">
<div class="panel panel-default">

Joomla 4 / 6

Use this instead

<div class="col-12 d-none d-sm-block">
<img class="img-fluid">
<div class="card">

How to fix it

1col-xs-* → col-*.
2img-responsive → img-fluid.
3hidden-xs → d-none d-sm-block.
4well / panel → card.

Also known as

col-xs · img-responsive · hidden-xs · well · panel · Bootstrap 3

Scan a ZIP for this Ask Infyways to fix it

CSS-OFFSET-INVISIBLE-001

offset2 hide element-invisible input-block-level

offset* / hide / show / element-invisible / input-block-level

These Bootstrap 2 utility classes are searched on their own. They are not in Bootstrap 5.

offset2 hide element-invisible input-block-level → offset-* / d-none / d-block / visually-hidden / form-control w-100

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Mechanical renameCSS / Bootstrap

Symptoms people search

hidden content showing · input full width gone · offset broken

Replace this code

Swap offset2 hide element-invisible input-block-level for offset-* / d-none / d-block / visually-hidden / form-control w-100.

Joomla 3

Remove or stop calling this

<div class="span6 offset2 hide">
<input class="input-block-level">
<span class="element-invisible">Label</span>

Joomla 4 / 6

Use this instead

<div class="col-md-6 offset-md-2 d-none">
<input class="form-control w-100">
<span class="visually-hidden">Label</span>

How to fix it

1offset2 → offset-md-2 (etc).
2hide/show → d-none / d-block.
3element-invisible → visually-hidden.
4input-block-level → form-control w-100.

Also known as

offset2 · offset3 · element-invisible · input-block-level · d-none · visually-hidden

Scan a ZIP for this Ask Infyways to fix it

JLAYOUT-CLASS-001

JLayout

JLayout class name

JLayout is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JLayout" not found.

JLayout → Joomla\CMS\Layout\LayoutInterface

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JLayout" not found
Class 'JLayout' not found
Failed to open stream: JLayout

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JLayout for Joomla\CMS\Layout\LayoutInterface.

Joomla 3

Remove or stop calling this

JLayout::getInstance();
// or new JLayout()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Layout\LayoutInterface;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Layout\LayoutInterface.
2Replace every JLayout with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JLayout · Joomla\CMS\Layout\LayoutInterface · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JLAYOUTFILE-CLASS-001

JLayoutFile

JLayoutFile class name

JLayoutFile is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JLayoutFile" not found.

JLayoutFile → Joomla\CMS\Layout\FileLayout

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JLayoutFile" not found
Class 'JLayoutFile' not found
Failed to open stream: JLayoutFile

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JLayoutFile for Joomla\CMS\Layout\FileLayout.

Joomla 3

Remove or stop calling this

JLayoutFile::getInstance();
// or new JLayoutFile()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Layout\FileLayout;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Layout\FileLayout.
2Replace every JLayoutFile with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JLayoutFile · Joomla\CMS\Layout\FileLayout · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

JLAYOUTHELPER-CLASS-001

JLayoutHelper

JLayoutHelper class name

JLayoutHelper is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JLayoutHelper" not found.

JLayoutHelper → Joomla\CMS\Layout\LayoutHelper

Dies at Joomla 5 → 6

Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

Class "JLayoutHelper" not found
Class 'JLayoutHelper' not found
Failed to open stream: JLayoutHelper

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JLayoutHelper for Joomla\CMS\Layout\LayoutHelper.

Joomla 3

Remove or stop calling this

JLayoutHelper::getInstance();
// or new JLayoutHelper()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Layout\LayoutHelper;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

1Add a use statement for Joomla\CMS\Layout\LayoutHelper.
2Replace every JLayoutHelper with the short class name from that use line.
3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JLayoutHelper · Joomla\CMS\Layout\LayoutHelper · class alias · J prefix

Scan a ZIP for this Ask Infyways to fix it

PAGINATION-MAGIC-001

function pagination_item_active($item)

Magic pagination_item_active functions

Joomla 3 templates defined global functions in pagination.php. Joomla 4 removed that hook.

function pagination_item_active($item) → Layout joomla.pagination.link

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4You rewrite thisTemplates

Symptoms people search

pagination looks like unstyled html · pagination_item_active ignored

Replace this code

Swap function pagination_item_active($item) for Layout joomla.pagination.link.

Joomla 3

Remove or stop calling this

function pagination_item_active($item) {
    return '<a href="' . $item->link . '">' . $item->text . '</a>';
}

Joomla 4 / 6

Use this instead

Override layouts/joomla/pagination/link.php in the template html/ folder.

How to fix it

1Delete the magic functions.
2Copy Cassiopeia/Atum pagination layouts and edit those.

Also known as

pagination_item_active · pagination_list_render

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

TPL-ATUM-001

ISIS / Hathor

Atum admin template

Atum is the Joomla 4+ administrator template. ISIS overrides will not match its markup.

ISIS / Hathor → Atum (+ child if you brand the admin)

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Removed — fatalJ4: Works nativelyJ6: Works nativelyBC plugin: no — already dead on J4Architecture change — no auto-fixTemplates

Symptoms people search

admin unstyled · Atum · icon-32

Replace this code

Swap ISIS / Hathor for Atum (+ child if you brand the admin).

Joomla 3

Remove or stop calling this

administrator/templates/isis

Joomla 4 / 6

Use this instead

administrator/templates/atum
Recreate html/ overrides from Atum layouts.

How to fix it

1Assign Atum.
2Copy overrides from Atum, not ISIS.
3icon-32-* sprites are gone.

Also known as

Atum · icon-32 · Hathor

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

TPL-BEEZ-001

Beez3

Beez / Beez3 templates

Beez was a Joomla 1.6–3 accessibility template. It is not in Joomla 4.

Beez3 → Cassiopeia

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Architecture change — no auto-fixTemplates

Symptoms people search

beez template missing

Replace this code

Swap Beez3 for Cassiopeia.

Joomla 3

Remove or stop calling this

templates/beez3

Joomla 4 / 6

Use this instead

Cassiopeia or a modern template. Beez is gone.

How to fix it

1Switch to Cassiopeia or a current accessible template.

Also known as

Beez · Beez3

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

TPL-CASSIOPEIA-001

Protostar fork

Cassiopeia (do not fork Protostar)

Cassiopeia is the Joomla 4+ site template. Forking Protostar keeps Bootstrap 2 forever.

Protostar fork → Cassiopeia + child template

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Removed — fatalJ4: Works nativelyJ6: Works nativelyBC plugin: no — already dead on J4Architecture change — no auto-fixTemplates

Symptoms people search

how do I replace protostar · Cassiopeia child

Replace this code

Swap Protostar fork for Cassiopeia + child template.

Joomla 3

Remove or stop calling this

Copy templates/protostar to templates/mytemplate

Joomla 4 / 6

Use this instead

Create a child of Cassiopeia. Put CSS in user.css. Overrides in html/.

How to fix it

1Start from Cassiopeia.
2Use a child template so core updates survive.

Also known as

Cassiopeia · child template · user.css

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

TPL-COMPONENT-PHP-001

templates/protostar/component.php

component.php error chrome

Error and print views use a reduced document. Old component.php often still loads MooTools/Bootstrap 2.

templates/protostar/component.php → Cassiopeia/Atum component.php (clean document)

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Changed behaviourJ6: Changed behaviourBC plugin: not applicableYou rewrite thisTemplates

Symptoms people search

print page unstyled · error.php broken · component.php

Replace this code

Swap templates/protostar/component.php for Cassiopeia/Atum component.php (clean document).

Joomla 3

Remove or stop calling this

Joomla 3 component.php loading the whole template chrome for errors/print

Joomla 4 / 6

Use this instead

Use the J4+ component.php. Error documents are cleaner — do not assume Protostar head assets.

How to fix it

1Replace component.php from Cassiopeia.
2Load assets via WAM only.

Also known as

component.php · error.php

Scan a ZIP for this Ask Infyways to fix it

TPL-FAVICON-001

favicon.ico in Joomla root wins

Favicon: root vs template

Joomla 4 template assets take over favicon resolution.

favicon.ico in Joomla root wins → Template favicon wins on Joomla 4+

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Changed behaviourJ6: Changed behaviourBC plugin: not applicableYou rewrite thisTemplates

Symptoms people search

wrong favicon after upgrade · favicon.ico

Replace this code

Swap favicon.ico in Joomla root wins for Template favicon wins on Joomla 4+.

Joomla 3

Remove or stop calling this

/favicon.ico in the site root always showed

Joomla 4 / 6

Use this instead

Put favicon in the template (Cassiopeia media / joomla.asset.json). Root favicon is no longer the winner.

How to fix it

1Add the icon to the template.
2Clear browser cache after the change.

Also known as

favicon

Scan a ZIP for this Ask Infyways to fix it

TPL-ISIS-001

ISIS

ISIS / Hathor admin templates

ISIS and Hathor were removed. Joomla 4+ admin is Atum (Bootstrap 5). Admin overrides copied from ISIS layouts will not match Atum markup.

ISIS → Atum

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Architecture change — no auto-fixTemplates

Symptoms people search

administrator looks broken · isis template not found · hathor missing

Replace this code

Swap ISIS for Atum.

Joomla 3

Remove or stop calling this

administrator/templates/isis

Joomla 4 / 6

Use this instead

administrator/templates/atum — restyle with a child if you must brand the admin.

How to fix it

1Use Atum.
2Recreate html/ overrides from Atum layouts, not ISIS.
3Replace icon-32-* toolbar sprites with Atum icon classes.

Also known as

ISIS · Hathor · Atum · icon-32

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

TPL-JDOC-HEAD-001

<jdoc:include type="head" />

jdoc:include type="head"

type=head still works. Joomla 4+ templates split the include so you can put CSS in the head and JS before </body>.

<jdoc:include type="head" /> → Split metas / styles / scripts includes

Dies at Joomla 4 → 5

Dies at Joomla 4 → 5J3: Works nativelyJ4: Works nativelyJ6: Changed behaviourBC plugin: not applicablePatch possible — review itTemplates

Symptoms people search

scripts in head blocking · jdoc head

Replace this code

Swap <jdoc:include type="head" /> for Split metas / styles / scripts includes.

Joomla 3

Remove or stop calling this

<jdoc:include type="head" />

Joomla 4 / 6

Use this instead

<jdoc:include type="metas" />
<jdoc:include type="styles" />
<jdoc:include type="scripts" />

How to fix it

1Prefer the split includes when you custom-build a template.

Also known as

jdoc:include type="head" · type="metas"

Scan a ZIP for this Ask Infyways to fix it

TPL-MODULES-PHP-001

templates/protostar/html/modules.php

modules.php chrome (Bootstrap 2)

J3 module chrome copied well/span/row-fluid. Those classes do nothing on Cassiopeia.

templates/protostar/html/modules.php → Cassiopeia module chrome + BS5 classes

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Changed behaviourJ6: Changed behaviourBC plugin: no — already dead on J4You rewrite thisTemplates

Symptoms people search

module layout broken · modules.php · modChrome

Replace this code

Swap templates/protostar/html/modules.php for Cassiopeia module chrome + BS5 classes.

Joomla 3

Remove or stop calling this

function modChrome_well($module, &$params, &$attribs) {
    echo '<div class="well span3">';
}

Joomla 4 / 6

Use this instead

Rebuild chrome with card / module-default from Cassiopeia. Use Bootstrap 5 classes.

How to fix it

1Replace chrome functions from a J4+ template.
2Update module class suffixes in the admin.

Also known as

modules.php · modChrome · xhtml chrome

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it

TPL-PROTOSTAR-001

Protostar

Protostar site template

Protostar was the Joomla 3 site template. It is not in Joomla 4+. Copying the folder forward keeps Bootstrap 2 and MooTools assumptions. That is not a migration.

Protostar → Cassiopeia (or a Joomla 4+ template), preferably a child template

Dies at Joomla 3 → 4

Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Architecture change — no auto-fixTemplates

Symptoms people search

site template missing after upgrade · protostar not in template list · ugly unstyled site

Replace this code

Swap Protostar for Cassiopeia (or a Joomla 4+ template), preferably a child template.

Joomla 3

Remove or stop calling this

templates/protostar/index.php with JHtml::_('bootstrap.framework')

Joomla 4 / 6

Use this instead

templates/cassiopeia (core) or a child of Cassiopeia. Use joomla.asset.json. Do not fork Protostar.

How to fix it

1Do not zip Protostar and install it on Joomla 4/5/6.
2Start from Cassiopeia or a current club template.
3Re-apply design with a child template and user.css — not a Protostar fork.

Also known as

Protostar · protostar

There is no 1:1 swap for this one. The architecture changed. If you cannot rewrite it, Infyways can.

Scan a ZIP for this Ask Infyways to fix it