Using a CSS Client Extension

Using a CSS Client Extension

Available Liferay 7.4

With a CSS client extension, you can override page styles without a theme or dependencies on Liferay’s code. Start with a client extension (from the sample workspace).


To start developing client extensions,

  1. Install Java (JDK 8 or JDK 11).


    Check the compatibility matrix for supported JDKs, databases, and environments. See JVM Configuration for recommended JVM settings.

  2. Download and unzip the sample workspace:

    curl -o\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip

Now you have the tools to deploy your first CSS client extension.

Examine and Modify the Client Extension

The CSS client extension is in the sample workspace’s client-extensions/liferay-sample-global-css/ folder. It’s defined in the client-extension.yaml file:

    name: Liferay Sample Global CSS
    type: globalCSS
    url: global.css

The client extension has the ID liferay-sample-global-css and contains the key configurations for a CSS client extension, including the type and the CSS file to add. See the CSS YAML configuration reference for more information on the available properties.

It also contains the assemble block:

    - from: assets
      into: static

This specifies that everything in the assets/ folder should be included as a static resource in the built client extension .zip file. The CSS file in a CSS client extension is used as a static resource in Liferay.

The assets/global.css file contains this CSS:

.logo::after {
   color: #0054f0;
   content: 'Liferay Sample Global CSS';
   margin-left: 2rem;

This modifies the color of the Liferay logo for the home page when the client extension is enabled.

Add CSS to modify the background color for buttons. Open the global.css file, add a declaration for the .btn-primary class, and specify the background-color:

.btn-primary {
    background-color: purple;

Now deploy the client extension.

Deploy the Client Extension to Liferay

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:

Sign in to Liferay at http://localhost:8080. Use the email address and the password test. When prompted, change the password to learn.

Once Liferay starts, run this command from the client extension’s folder in the sample workspace:

../../gradlew clean deploy$(docker ps -lq)

This builds your client extension and deploys the zip to Liferay’s deploy/ folder.


To deploy your client extension to Liferay Experience Cloud, use the Liferay Cloud Command-Line Tool to run lcp deploy.


To deploy all client extensions in the workspace simultaneously, run the command from the client-extensions/ folder.

Confirm the deployment in your Liferay instance’s console:

STARTED sample-global-css_1.0.0

Now that your client extension is deployed, configure Liferay to use it.

Use the Client Extension on a Page

Configure a page in Liferay to use your deployed client extension:

  1. On a page with at least one button, click the Edit icon Edit icon at the top.

  2. In the sidebar, navigate to the Page Design Options menu (Page Design Options icon) and click the configuration icon (Configuration icon) at the top of the menu.

    Click the cog wheel icon in the Page Design Options menu to access this client extension's configurations.

  3. In the CSS Client Extensions section toward the bottom of the page, click Add CSS Client Extensions.

    Add the CSS client extension from the list.

  4. Select your CSS client extension from the pop-up modal and click Add.

  5. Click Save.

Now your client extension is configured. In the page editor, the background color on the buttons is now the color your CSS specifies. To see your CSS applied on the page outside Edit mode, you must publish the page.

If you changed the background color in your client extension's global.css file, all buttons on the page were changed.


If the buttons on the page still show the default background color, do a hard refresh of the page to clear your browser’s cache (CTRL + SHIFT + R for most browsers). If you change your client extension and redeploy it, you may need to remove it from the page and re-add it to see the changes.

Next Steps

You have successfully used a CSS client extension in Liferay. Next, try deploying other client extension types.