Introduction
When developing in Liferay DXP or Liferay 7.4+, you’ll encounter various ways to customize the look and feel of your portal. Two common methods are through CSS Client Extensions and Theme CSS Client Extensions. They might seem similar—both deal with adding CSS to your Liferay site, but they serve different purposes and have distinct use cases. In this blog, we’ll understand the differences, benefits, and when to use both client extensions.
Prerequisites
Liferay DXP
Basic knowledge of Liferay
What is Client Extension?
A Client Extension in Liferay is a method for extending and customizing Liferay’s functionality without directly modifying the core platform.
CSS Client Extension
- Purpose :
To inject custom CSS into your Liferay site that applies globally or to specific parts of your portal.
- Key Features :
Targets global styles.
Can override portal or theme styles.
Lightweight and easy to maintain.
Does not require a full theme or war deployment.
- Use Case :
You want to change the style of a few components (e.g., button colors, layout margins) across all pages without building a custom theme.
- Steps To Create a CSS Client Extension :
Step 1 : Create folder structure
Create a folder structure for the client extension. First, create a client-extension folder in your workspace. For that, you can refer to this image for the folder structure.
Step 2 : Add CSS and YAML file content
Add content into your client-extension.yaml file and global.css file.
This CSS client extension will change the appearance of the button on the page where it is applied in the configuration.
For building and deploying the client extension, you can use these commands.
./gradlew build -p client-extension/your_client-extension_name
./gradlew deploy -p client-extension/your_client-extension_name
Theme CSS Client Extension :
- Purpose :
Its main purpose is to modify or override the theme without creating a full theme.
- Key Features :
Tied to a specific theme ID.
Injected after the theme CSS, so it’s ideal for overrides.
Useful for multi-site deployments using the same theme base with minor styling differences.
- Use Case :
You have multiple sites using the same theme, but one site needs slightly different header styling or footer spacing.
- Steps to create Theme CSS Client Extension :
Step 1: Create folder Structure :
For that, you refer to the above image.
Step 2: Add CSS and YAML file content :
This will change the color of the control menu of Liferay.
Key Differences :
| Feature | CSS client-extension | Theme CSS client-extension |
| Scope | Applies globally across the entire Liferay instance. | Applies only to a specific theme. |
| Applied When | To style specific elements or pages | To extend or override existing Liferay themes |
| Ideal for | It is ideal for making basic changes to the UI, like buttons, headings, etc., and fixing basic styling issues. | It is ideal only when you want to modify the theme-specific elements. |
| Deployment Flexibility | It has more flexibility than the theme CSS client extension. | It has good flexibility, but not as good as the CSS client extension, because for multiple themes, we have to create multiple extensions. |
| Theme Dependency | It is not theme-dependent. | It is highly dependent on the theme. |
| Potential Conflicts | May cause unintentional styling conflicts if multiple CSS extensions are applied. | Less chance of conflicts since styles are connected to a specific theme. |
Can We Use Both?
Yes, it’s common to combine both. Use the CSS Client extension for base styling that applies across all sites, and the Theme CSS Client extension for theme-specific overrides.
Conclusion
Understanding the difference between CSS and Theme CSS Client Extensions in Liferay helps you choose the right tool for your customization needs. For simple, global changes, CSS Client-Extension is your go-to. For theme-aware customization, Theme CSS Client-Extension gives you precision without the overhead of a full theme project. By leveraging Client Extensions properly, you keep your code modular, scalable, and easier to maintain—perfect for modern enterprise Liferay development.
