Theming in Liferay 7.1


In this article I’ll try to give you a comprehensive picture of the current state of theming in Liferay 7.1. To do this, I’ll describe the evolution of Liferay theming from the early Bootstrap use in 6.x themes to the introduction of Lexicon for 7.0, as well as identifying and addressing challenges that have been changed in 7.1. Also, I’ll add some practical cases that could help you when building themes and themelets depending on your choices.

The (ab)use of Bootstrap

Before getting into what is Lexicon, we need to talk about Bootstrap. Because it has been used in Liferay since 6.2 — and still used in a way but we’ll see that later — and as web developers we certainly used it at one time or another.

Bootstrap is a CSS framework: it gives you a set of CSS classes ready to use in order to build user interfaces.

Bootstrap is not a design language: it doesn’t provide a proper design system to improve your user experience through consistent interfaces.

And I’m sure that you already experienced the problem that comes with, because the unfortunate consequence can look like this:

Of course, this list is not exhaustive. Sadly, you can imagine a lot more combinations (e.g. with positioning).

It’s a common case to use Bootstrap as a CSS framework and a design language. Bootstrap design system is kind of implicit because its current rules are imprecise. For example:

“Bootstrap includes several predefined button styles, each serving its own semantic purpose, with a few extras thrown in for more control.”

Source: Bootstrap documentation

What does this really mean? In my previous use case of Save/Cancel, is it ok to use .btn-danger when it’s dangerous to cancel and .btn-default when it’s safe within the same application? As it is, we could say that all of our previous interfaces are following Bootstrap rules. But the user experience can become a nightmare.

So in order to create the best UX/UI design for your application, you need a proper design system you can rely on.

Understanding Lexicon

Liferay’s own design system

The new design of Liferay 7.0 is not just a new classic theme with a Bootstrap upgrade. Design in Liferay is more important than ever. And based on what we mentioned previously, Liferay needed a proper design system. Consequently, Lexicon has been created.

Lexicon is not a CSS framework: “it is just a set of patterns, rules and behaviors.”

Lexicon is a design language: “a common framework for building interfaces within the Liferay product ecosystem.”

Source: Lexicon documentation

It’s the opposite definition we made about Bootstrap. But unlike it, you can’t be misled and use Lexicon as a CSS framework since it doesn’t provide any ready-to-use code.

To continue with our button example, here’s a sample of what you can find about it with Lexicon:

example of Do's and Don'ts for buttons

Source: Lexicon documentation

Lexicon helps designers

If Lexicon is not like Bootstrap, we can compare it to Google Material Design, Microsoft Metro or iOS Design. And just like them, Lexicon is for designers. In order to create the look and feel of an application, designers need two important documentations: the graphic charter — designers may have built themselves, but not necessarily — and the design language system.

Taking our previous example with buttons, the graphic charter would define what is the color and shape of our primary button in order to reflect the graphical identity of the company and/or the product. Whereas the design language would define in which cases to use primary buttons and how to use them in order to ensure an integration with consistency in its ecosystem.

Let’s consider this statement:

Following Material Design System to create the look and feel of an Android application guarantee that your application will integrate properly within Android ecosystem.

Now the same philosophy applies for Liferay:

Following Lexicon Design System to create the look and feel of a Liferay site guarantee that your site will integrate properly within Liferay ecosystem.

More components

The set of components — or pattern library — is defined by the design language system. Yet another part where Bootstrap is misleading in its role. But now with Lexicon, the number of components can be expanded as needed. And most importantly, the list of its components is not bounded to what Bootstrap provides, and thus to Bootstrap upgrades.

A concrete example is the timeline components available in Liferay 7.1 but missing in Bootstrap 4.

Implementing Lexicon

Lexicon CSS becomes Clay

In 7.0, Liferay implemented Lexicon to apply its guidelines to a new look and feel and called it Lexicon CSS. But I guess the name added too much confusion. So now in Liferay 7.1, Lexicon’s implementation is Clay.

Where is Bootstrap?

Bootstrap is not gone with the arrival of Lexicon and Clay. Liferay 7.0 used Bootstrap 3 and now Liferay 7.1 uses Bootstrap 4, but to what extent? Where is Bootstrap?

Well, Bootstrap is used as a base framework in Clay, so Clay is an extension of Bootstrap. In other words, Clay provides existing CSS classes from Bootstrap as well as new CSS classes, all of them built to be Lexicon compliant.

For example, if you want do define an HTML element as a fluid container you can use .container-fluid (Bootstrap). But if you want a fluid container that doesn’t expand beyond a set of width you can also use .container-fluid-max-* classes (Clay).

What about icons?

Lexicon provides a set of icons. Clay implements it as a set of SVG icons. But you are free to use another icon library of your choice such as Font Awesome or Glyphicons.

What is Clay Atlas?

Clay Atlas is the default base theme in Liferay.

Because Lexicon is a design language, you could imagine building an equivalent of Clay, either from scratch or on top of your favorite CSS framework (e.g. Bootstrap, Foundation, Bulma) to integrate in another product than Liferay.

For example, we could imagine an implementation called Gneiss with two themes named Alps and Himalayas:



With this diagram, we highlight the role of each implementation and possibilities that come with:

  • Multiple Lexicon implementations

  • Multiple themes for Lexicon implementations

  • Multiple custom themes extending from a parent theme

In Liferay, you can either build a theme independent of Atlas, or based on Atlas.

Theme implementation concerns

This part will not cover all the steps required to create a theme because Liferay documentation does it properly. We will focus on the building process and some parts that need your attention.

Clay vs Bootstrap

In Liferay 6.2, Liferay used Bootstrap components, and so did you. So when it came to customization, you wanted to customize Bootstrap.

But as we saw in this article, Clay is an extension of Bootstrap, and Liferay is now using Clay components instead of Bootstrap components. So now, you want to use Clay components too and thus, you want to customize Clay instead of Bootstrap.

For example, alerts for error messages with Clay:

<div class="alert alert-danger" role="alert">
	<span class="alert-indicator">
		<svg aria-hidden="true" class="lexicon-icon lexicon-icon-exclamation-full">
			<use xlink:href="${images_folder}/clay/icons.svg#exclamation-full"></use>
	<strong class="lead">Error:</strong>This is an error message

Instead of alerts with Bootstrap:

<div class="alert alert-danger" role="alert">
  Error: This is an error message

Check out available components on Clay’s site.

Customizing Clay

Even if — for some reason — you still want to use Bootstrap components, you need to customize Clay components because Liferay is using them and consequently your users will experience them. If you’re only customizing Bootstrap components, Clay components would have only a part of the customization and the user experience would be inconsistent (e.g. successful alerts after a save/submission).

Customizing Clay is the same process as Bootstrap: you want to work with SCSS files in order to override variables. You can find these variables in the official GitHub repository.

Do you remember when you could customize Bootstrap online and download the result?


For each variable in Bootstrap, you had a corresponding input. So customization was quick and handy.

Guess what? Now there’s an awesome tool like that for Clay called Clay Paver (v1 for Liferay 7.0, v2 for 7.1).



IMHO, it’s actually better because you can preview the result online while you’re editing.

It’s open source on GitHub and you can run it locally. So if you like it, please star it to support its author Patrick Yeo for providing such a great tool to the community.

Integrating a Bootstrap 4 theme

In this case, you want to use an existing Bootstrap 4 theme and build a Liferay theme from it. You can find examples here where I built Liferay 7.1 themes from Bootstrap 4 themes using Liferay documentation.

However, each Bootstrap theme can be built differently so you run into problems when you want to integrate it in a Liferay theme. So, we’re going to take a closer look at some of the potential pitfalls.

Use SCSS files

You need to use the uncompiled version of the Bootstrap theme, i.e. multiple SCSS files.

These SCSS files are included in a subfolder to ${theme_root_folder}/src/css as mentioned in the documentation.

Don’t use a compiled CSS file (e.g. my-bootstrap-theme.css or my-bootstrap-theme.min.css). If you’re working from a Bootstrap theme that doesn’t include SCSS files, you need to ask for them because these files should be provided.

Verify variables

In some cases, a Bootstrap theme is using custom variables. For example, instead of $primary it could be something like $custom-color-primary, and thus $primary is not overridden when integrating your Bootstrap theme in your Liferay theme.

The less painful way to resolve this is to map custom variables with Bootstrap variables in a dedicated file (e.g. _map_variables.scss):

$primary: $custom-color-primary;

This dedicated file is then imported into _clay_variables.scss.

Choose your icon provider

In your Bootstrap 4 theme, there’s a great chance that it doesn’t use Font Awesome 3 which is include in Liferay. In that case, you can:

  • Add Font Awesome (4+) in your theme

  • Downgrade Font Awesome icons (not recommended, can be problematic for theme consistency and if icons don’t exist in Font Awesome 3)

  • Migrate to Lexicon icons


The new UI experience in Liferay 7 is not a simple “modern, refreshed look”. As a developer, we might have felt like it was, considering that Lexicon & Clay were new things introduced by Liferay that didn’t require our attention because Bootstrap’s still here. But there’s so much work and thinking behind website design with Lexicon and Clay that understanding it becomes the key to building and extending Liferay themes. And I hope this article helped you with that.






Liferay 7.0 on Themes

Liferay 7.1 on Themes


Introducing Lexicon: The Liferay Experience System

New Improvements in Lexicon: Features for Admin and Sites


Lexicon update in Liferay 7.1 from 7.0

Designing animations for a multicultural product

How Good Design Enhances Utility


Clay Paver

Liferay on Dribbble

Liferay Design Site


"Even if — for some reason — you still want to use Bootstrap components, you need to customize Clay components because Liferay is using them and consequently your users will experience them."


That sounds horrible only to me? Frankly I am still using 6 but, given my experience, I would want to build my themes on top of pure Bootstrap and have nothing Liferay in it. Now I would't mind if Liferay code existed but affected only Liferay components. That is one of the reasons I don't like the 7 redesign where the control panel integrates with the sites. Actually I hate pretty much all client side Liferay tech :) I think that for 7 I will have to learn how to use it in headless style because it is still an great CMS.

Thank you for your feedback :) I totally understand your concerns. If you want to build themes on top of pure Bootstrap, you could, but you will experience some inconsistency in your site. For example, default alerts from Liferay are Clay components and not Bootstrap components. So if you only customize on top of Bootstrap, you will have slightly different styles with alerts. So Clay customization is highly recommended in this perspective, but not mandatory. You can checkout this examples : It’s simply an integration of Bootstrap themes without customizing Clay components. I’d be glad to have your thoughts about this. And if you want to use Liferay in an headless way, you might be interested in this Liferay project :

I was really enjoying the article but I had to pause reading when I reached the error message example... :-(


Bootstrap: error message = 3 lines / 88 chars


Clay: error message = 8 lines / 326 chars


The Clay example adds no functionality. It's still an error message. Nothing more. Why should the developer have to write so much more code?


We need simplification, not complexification.


I'll continue reading now.


Those HTML snippets represent the result in the DOM, but in practice, the developer won't have to write this lines in pure HTML. Here's examples of what it looks like for a developer depending on the front technology he chose :



Soy & Web components:


I hope this make it clearer on the apparent complexity Clay is adding.

Thanks for your feedback!