joomla bootstrap

In September 2012, the Joomla project released the new major version 3.0 of his CMS, including Bootstrap (BS) 2.3.x as frontend framework (FF) library. It was great at that time, Joomla became the first out of the box responsive CMS on the market. The problem was that bootstrap should only be used in the Protostar template on layout overrides. Instead of, the core was soaking Bootstrap up and nowadays the whole Joomla CMS code is filled with Bootstrap 2.3 markup.

Bootstrap did evolve and released some new major versions which did break backwards compatibility. Because of that, the Joomla CMS can't update within a major version to a new Bootstrap major version like BS 3. This article will explain why no upgrade can't be made, the problems with BS 3 templates and how to solve the vendor lock in.

The semver problem

Joomla follows semantic versioning, so we can't change in the Joomla 3 series to Bootstrap 3 or 4 because it would break backwards compatibility. The Joomla CMS needs to stick with Bootstrap 2.3, despite the fact that Bootstrap 2 is end of life since ages. Yes, we are using heavily a not maintained version of Bootstrap as frontend framework.

I'm sure that Joomla 4 would be released already if we didn't get stuck with a Bootstrap major version. Joomla's major releases are some kind bound to the Bootstrap major release cycle, which is a bad situation.

bootstrap migrate

Problems with a BS 3 template

Bootstrap 3 is the most popular version (yes I know, Bootstrap 4 is on it's way) to create web sites with and has a large user base since years. For the template developers it is a selling point when their template runs on BS 3. Now we have the situation that many templates are running on BS 3. Because of the Joomla layout override system, which is great by the way, it is possible to create a template with Bootstrap 3 in Joomla 3 very easily. But the site admin who is installing a BS 3 template will face the following problems:

Javascript errors

The Javascript code of Bootstrap 2 and 3 does not work well together on the same page. Javascript errors do happen and can break your site. Through some overloading techniques it can be prevented to load both scripts, but it will be very likely that other errors will happen.

Functionality not ported back

The layouts do need to be copied to the template and adjusted to BS3. New functionality in the views are not automatically ported to the template override. Either way the site admin is doing it or the template developer ships a new release of it's template. Hopefully you didn't change the template override, because then the change got reverted during the template upgrade.

Security issues are not fixed

If there will pop up a security issue in a layout of the core, then the templates do need to be adjusted. Updating Joomla with the fix is not enough! The template developer needs to provide the fix to it's user. Pray that you are not using a not maintained template.


Extensions do need to support BS 2 out of the box. You as site integrator will need to find a way to make the extension work properly with BS3 then. Either way you have to create the layout overrides by hand or you are lucky and the extension is supporting BS 3 as well. It can do that by skipping Bootstrap and use a different library, then the extension does not look tightly integrated. Or it can load it's own namespaced Bootstrap CSS, both ways do bloat the site.

bootstrap migrate error

What happens when we upgrade the core to BS 4?

Site Admin

It will be very likely that upgrading from Joomla 3 to 4 will be a one click upgrade. This is true for the PHP code, but not for the template. You need to create a new template which works with BS 4, if it is BS2 based. If it is BS3 based, then you need to adapt all the overrides to work with Joomla 4. It's a kind of big bang upgrade, let's cross the fingers and pray that all is going good. Hopefully you don't maintain large Joomla sites, upgrade will be a pain.

Extension developer

Extension developers do need to support in their extensions BS2, need to find a way to work with BS3 and must be compatible with BS4. For quite some time they need to provide their extensions for Joomla 3 and 4. Either way, the extension providers will have the following options to develop their extensions:

  • Maintain wo different code bases of the extension.
  • Stop developing for Joomla 3.
  • Find a way to deal with it by using a namespaced or different library of FF.
  • Just give up and move to Wordpress.

It will be almost the same as with Joomla 2.5 and 3.

Why we need some transition layer?

The goal must be, to isolate bootstrap related code in the core. If that happened, then we can introduce new FF libraries or their major versions much faster within the same Joomla major version. Under every circumstance, the template needs to define with which frontend framework version it want's to work with. The job of the core is to load the right layouts and views then. Good would be if there can be some kind of layout inheritance, where the framework related layout can parameterise and call the default layout. This would avoid duplicated code.

The benefit would be that we are able to introduce in Joomla 3 BS4 and deprecate BS2. The site admin can then make a copy of the template, migrate it to Bootstrap 4 and assign page by page to the new template. If all pages are done, then the upgrade to Joomla 4 will be possible without any issue. In Joomla 4 BS2 can then be removed. If BS 5 comes up, then we can easily introduce it in the core and create layouts for it.

Additionally, the transition to a new frontend framework library like foundation would be then much easier. How such a transition layer can look like is described in this RFC pull request. We made a 100% backward compatible proof of concept with a new Joomla BS3 template in Joomla 3 without any override. It describes one possible way. I'm sure there will be others, all will have their pros and cons. But now is the point to find a unified way to deal with that problem for template devs, site administrators and extension developers. The mess becomes bigger with every new major version of Bootstrap as we have a battlefield already with BS 2 and BS 3.


The problems I'm describing here are real world issues, we at Digital Peak are facing them on our daily business. Talking with site integrators, other extension developers, template devs or just Joomla users, all do suffer from the bootstrap problem in Joomla. It is up to us to provide a way to deal with this situation properly, NOW! Joomla 4 is around the corner and according to the roadmap, the last minor version where we can introduce such a transition layer will be version 3.8. So lets do a decision!

Important is that we learn from the past.


joomla love

We use cookies on our website. Some of them are essential for the operation of the site, while others help us to improve this site and the user experience (tracking cookies). You can decide for yourself whether you want to allow cookies or not. Please note that if you reject them, you may not be able to use all the functionalities of the site.