Bootstrap 3 in Liferay 6.2, yes! that's possible

Hey guys, today I am going to speak about a concurrent topic, how to replace Bootstrap 2.3.2 CSS in Liferay 6.2 for new Bootstrap 3.x, I have received a lot of questions about it, and I helped all I was able, but I think this post and GitHub repository with a theme example can help more than some emails.


Before all else, I would like to say that the solution which I provide today is a personal work (not official) and only one of many ways to achieve it but for me it is the easier way because we only change the theme.


Yes, I've written the word "replace". This solution remove Bootstrap 2.3.2. and add Bootstrap 3.x (4 in the near future). It is not a way to put Bootstrap 3 on top of Bootstrap 2.3.2, I can not recommend that solution for many reasons, for example: it would duplicate the CSS weight, there would be a lot of class conflicts, or it would be very difficult to define browsers compatibility in your project.

Of course, we can not replace all Bootstrap 2.3.2 classes references along Liferay portal only when you theme is applied, but they are not many classes to rescue, so we will extend those old classes from new Bootstrap 3.x equal clases, like an example: span6 will work as col-md-6.

it can sound hard but no worries, let's see step by step (or go directly to GitHub repository with an example):


We are going to create a new _styled theme based on Boostrap 3.x, so first of all, you will need create a new theme using new SDK based on gulp or normal SDK.

Did you know where Bootstrap 2.3.2 CSS files are located in your theme? No worries, they are in “css/aui” directory, so let's work into this directory.


1º Create new aui.css file in “css” directory, then we must delete Bootstrap 2.3.2 references in this aui.css, in this way Bootstrap 2.3.2 will be removed from our theme (files will be there, but they won't be loaded).




2º Now we are are going to add the new Bootstrap, so let's go to copy "Bootstrap 3.x sass-version" files into a new directory inside “aui” called "bs3" and reference it in aui.css.

We can use differents ways to get Bootstrap 3.x sass-version, download directly from Bootstrap-sass GitHub repository, using Bower, npm, gem or compass, as you prefer.




3º Well, we have interchanged Bootstrap versions, but all old classes which have been deleted/renamed in Bootstrap 3.x do not look well so they should be created as an extension of the equal classes in Bootstrap 3.x, for this we will use my CSS file named "_bs2_extender.scss" which will do all basic extensions.

Some examples about what this file does:




4º Some Liferay CSS components do not look so well as they should because they were based on Bootstrap 2.3.2, so to fix it we will add a file called “_bs_liferay_fixes.scss” which contains some adjustments.




Now we can deploy the theme and we should see something like this:




It’s done! you have a new Bootstrap 3.x_styled-theme with which you will be able to use as a base to build your Bootstrap 3.x Liferay 6.2 themes.

In “_bs2_extender.scss” file I have extended the classes I consider the minimum to work well in Liferay 6.2, but feel free removing or adding, even collaborating in GitHub repository of this theme.

I recommend to use this theme when we want to use Bootstrap 3.x upgrades like its grid or responsive facilities. If we are still writing Bootstrap 2.3.2 markup, It wouldn’t make much sense, so be smart about what Bootstrap version do you want to use.


Thanks guys! More info about what I’m working on, Liferay themes or Liferay general world on my twitter @marcoscava

I would like to see a base BS 3 theme on marketplace, so that my theme can really inherit that one.
There is a theme on process to be published but that can take a month more or less, you could use repository files and copy them into your theme to make your theme based on BS3
Marcos - As always well written and very helpful. You are a definitely a boost for Liferay theme development. Thanks again for this.
Thanks a lot!
Actually there are a lot of coworkers who are working hard behind themes: Patrick, Nate, Rob.., this year we have released Lexicon, new theme generator based on gulp, and new themes! emoticon yeah!
Hi Marcos. This article is really interesting.
In your opinion what kind of problems can be found if I take a template from a bootstrap 3 website and try to use it as a base of a new liferay theme ?
I think you shouldn't find much problem, the common "problem" is that if you change a base elements the UI administration elements will change, because they are also based on Bootstrap.

A little complex would be migrate a Bootstrap 2.3.2 based theme to use this new one, because normally we build in our theme over bootstrap 2.3.2 structure. Recently I've migrated in a quick exercise madrid-theme (based in bootstrap 2.3.2) to this new one based on Bootstrap 3.x, I think it was not to hard, you can see the commits in a new branch:
Hi Marcos - thanks for this post! I am looking to do this very thing for a new theme that we are creating that needs to newest bootstrap components.
One question - I notice that you have a boostrap.scss file that contains the single import statement, @import "bootstrap/bootstrap", whereas the twbs/bootstrap sass project contains a _bootstrap.scss file with many import statements... which should I use?
What are the newest bootstrap components? do you mean Bootstrap 3.3.6?
I could create a branch for each new Bootstrap version, but it could take me some days.

No need to create a branch - I am just trying to understand your approach.
After looking further, I see that you have moved the bootstrap.scss file inside of the bootstrap directory (removing the leading "_") and then importing this file in the boostrap.scss file in the bs3 folder. Just curious as to why this was done.
Oh! I see. I've just changed the theme structure to be closer to "sass-bootstrap", now there are not two _bootstrap.scss files, there is only one file in the exactly same way that bootstrap-sass, bootstrap-sass directory contains all scss files, you can see the commit:

By the way, I've created a 3.3.5 branch and master will be always the 3.x.x newest version.

Newest Bootstrap 3.x.x master:

Bootstrap 3.3.5 branch:
I've installed your solution from github and for the most part it works. I'm having an issue getting glyphicons to display. Here's my code
<a href="#top"><span class="glyphicon glyphicon-chevron-up"
aria-hidden="true"></span> Back to top</a>

Any suggestion would be much appreciated.
Hi Williams!

This solution updates the Bootstrap CSS, you could update glyphicons font too, or simply use the class of bootstrap 2.3.2 glyphicons:

<span class="icon-chevron-up"></span>
Actually I added the fonts and that way work as well with the original classes.
However it still seems like its not finding all of the bs3 classes.
All Bootstrap classes are there, for example:

Ok I have the following code:
<div class="container text-center">
<hr />
<div class="row">
<div class="col-lg-12">
<div class="col-md-3">
<ul class="nav nav-pills nav-stacked">
<li><a href="#">Link 1</a></li>
<li><a href="#">Link 2</a></li>
<div class="col-md-3">
<ul class="nav nav-pills nav-stacked">
<li><a href="#">Link 3</a></li>
<li><a href="#">Link 4</a></li>
<div class="col-md-3">
<ul class="nav nav-pills nav-stacked">
<li><a href="#">Link 5</a></li>
<li><a href="#">Link 6</a></li>
<div class="col-md-3">
<ul class="nav nav-pills nav-stacked">
<li><a href="#">Link 7</a></li>
<li><a href="#">Link 8</a></li>

With your setup, found at, this code does seem to produce the expected result seen in a non liferay app. In Liferay it acts like the nav-pills nav-stacked classes are being found even thought they are there?
Thank you for this really helpful article Marcos, easy to understand and to implement.
Excellent solution.
Hi Marcos,

How can we include bootstrap 3 fonts in the theme.

Thanks and Regards
Narsingh Pal
I will try to write a blog entry about it, because it's a little bit complex, thanks!
Hi Marcos,

Hopy you are doing well !!
Need your help on how to include Bootstrap3 fonts in 6.2 Bootstrap 3.x theme ?

Many thanks in advance !!

Narsingh Pal
You only need to import the font files, try to do a:

They are in this directory:

├── glyphicons-halflings-regular.eot
├── glyphicons-halflings-regular.svg
├── glyphicons-halflings-regular.ttf
├── glyphicons-halflings-regular.woff
└── glyphicons-halflings-regular.woff2

Import them and that's all :-D
Hi Marcos;
Question on the glyphicon font files - where in the theme directory structure should they be placed?
Looking in the _variables.scss file, I see the following:
$icon-font-path: if($bootstrap-sass-asset-helper, "bootstrap/", "../fonts/bootstrap/") !default;

Since $bootstrap-sass-asset-helper default value is false, I believe that the "../fonts/bootstrap/" is the one to use, but from where? Where does the folder get placed in the theme directory hierarchy? Directly under _diffs?

I tried that, but it did not appear to work. Any guidance would be appreciated - thanks!

Hi Chris,

The fonts are not included so my recommendation: doesn't touch the bootstrap variables file, change the vars in the theme basic structure: css/_aui_variables.scss, there you could write your best directory choice to place the fonts.

Keep in mind all bootstrap files will be compiled in aui.css, so this will be the base file.


I'm using this theme and everything works great (i guess), except dropdowns.
Is there any conflict between ALLOY dropdowns and Bootstrap 3 dropdowns?

Thank you. Sérgio Esteves.