How to Customize Liferay DXP Themes: A Step-by-Step Guide

Branding is one of the first things businesses care about when launching a portal. With Liferay DXP, you can go beyond the default look by customizing themes. Whether you’re adjusting colors, typography, or layouts, theming allows you to align the portal UI with your brand identity.

In this article, we’ll explore step-by-step how to customize a Liferay DXP theme, add Bootstrap utilities, and tweak Clay variables for a polished user experience.

1. Understanding Liferay Themes

A theme in Liferay controls the overall look of your site—colors, typography, header/footer, and portlet layouts.
Key files in a Liferay theme:

• liferay-look-and-feel.xml → theme definition
• src/css/custom.css → your overrides
• src/templates/portal_normal.ftl → page layout template
• build.gradle → build/deploy configuration

2. Creating a New Theme

From your terminal, run:

yo liferay-theme

Follow prompts:

• Name: custom-theme
• Liferay Version: 7.4 (or your version)
• Deployment: Gradle

After generation, deploy it:

./gradlew deploy

3. Adding Custom CSS

Add your styles in src/css/custom.css:

/* src/css/custom.css */
body {
  background-color: #f8fafc;
  font-family: 'Segoe UI', sans-serif;
}

a {
  color: #0055aa;
}

.portlet-title {
  font-weight: bold;
  border-bottom: 2px solid #0055aa;
}

4. Using Bootstrap Utilities

Liferay ships with Bootstrap + Clay. You can leverage Bootstrap’s utility classes without extra imports.

Example: Create a responsive grid in portal_normal.ftl:

<div class="container">
  <div class="row">
    <div class="col-md-8">
      <@liferay_portlet["runtime"] portletName="com_liferay_journal_content_web_portlet_JournalContentPortlet" />
    </div>
    <div class="col-md-4">
      <aside class="p-3 bg-light">Sidebar Content</aside>
    </div>
  </div>
</div>

5. Customizing Clay Variables

Clay provides SCSS variables for theming. Edit src/css/_custom.scss:

$primary: #0055aa;
$secondary: #e63946;
$body-bg: #f8fafc;

@import "clay/base";

Rebuild and deploy:

./gradlew deploy

6. Testing & Deployment

Once deployed, go to Control Panel → Look and Feel → Themes and apply your custom theme.

Check different devices to ensure responsive behavior is intact.

7. Common Issues

• CSS not applied? → Ensure you ran gradlew build and cleared browser cache.
• Bootstrap clash with Clay? → Prefer Clay variables; Bootstrap utilities usually work fine.
• Upgrades? → Avoid overriding Clay core files; keep changes in custom.css.

Customizing Liferay DXP themes allows you to deliver a branded, responsive, and user-friendly portal. With Clay + Bootstrap utilities, you get both power and flexibility.