Using a Theme Sprite Map Client Extension

Using a Theme Sprite Map Client Extension

Available Liferay 7.4 U45+/GA45+

With a theme sprite map client extension, you can override the default Clay sprite map used for icons on a page. Start with the sample workspace to build and deploy your client extension.


An SVG sprite map is an image that contains several icons grouped together, each with a unique ID. You can load the SVG and reference the individual icons by ID. This provides a slight performance improvement, as you can download and cache the sprite map once to display all the site icons.


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 theme sprite map client extension.

Examine the Theme Sprite Map Project

The theme sprite map client extension is in the sample workspace’s client-extensions/liferay-sample-theme-spritemap-1/ folder. It is defined in the client-extension.yaml file:

    name: Liferay Sample Theme Spritemap 1
    type: themeSpritemap
    url: spritemap.svg

The client extension has the ID liferay-sample-theme-spritemap-1 and contains the key configurations for a theme sprite map client extension, including the type and the sprite map file to add. See the Theme Sprite Map YAML Configuration Reference for more information on the available properties.

It also contains the assemble YAML 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 SVG sprite map in a theme sprite map client extension is used as a static resource in Liferay.


The sample project’s assets/spritemap.svg is a copy of the Clay icons sprite map used in Liferay. You won’t notice any changes in the UI as all the icons used in Liferay are present in the example sprite map.

Since a sprite map client extension replaces the entire sprite map on the selected page, make sure that you have all the necessary icons with their corresponding IDs to avoid missing icons.

Modify the Sprite Map

To change a specific icon, you must find the ID of the icon. You can inspect the HTML element to find this.

The navbar contains nine icons.

Given below are the IDs of the icons used on the top navbar.

Number Icon ID
1 Edit icon pencil
2 Cog icon cog
3 Simulation icon simulation-menu-closed
4 Analytics icon analytics
5 AB Testing icon test
6 Information icon info-circle
7 Global Menu icon grid
8 Search icon search
9 User icon user

To swap the pencil icon for a fish,

  1. Find the <symbol> tag corresponding to the ID of pencil inside assets/spritemap.svg. You must open the SVG file in a text editor to view this.

    <symbol id="pencil" viewBox="0 0 512 512">
       <path class="lexicon-icon-body" d="M490.9,363.4l-2.8-5.1C468.3,322.4,359.9,304,358.9,304l-2.4-0.1l-10.8,1.5c-16.9,3.9-31,15.7-50.5,33.8c-25.2-14.7-52.4-37.6-68.7-54.3c-16.7-17.1-39.9-47.7-52.4-71.6c22-21.6,37.4-38.7,38.4-61.7c0-1-13.8-110.1-48.9-131.7l0,0l-5.1-3.1c-9.6-5.7-27.5-16.4-49.3-16.4c-5.4,0-10.8,0.7-17,2.3c-6.9,2-13.3,4.8-20,9.1C55.9,23,26.2,46.7,11.7,78c-13.5,30.8-4.4,187.9,113.4,311c111.6,116.8,241.2,122.7,266.1,122.7c6.4,0,15.1-0.3,22.4-1.6l2.8-0.1l6.7-2.5c32.2-13.2,56.9-41.7,68.4-57.2C518.4,415.5,497.8,376.6,490.9,363.4L490.9,363.4z" fill="none"></path>
       <path class="lexicon-icon-outline" d="M490.9,363.4l-2.8-5.1C468.3,322.4,359.9,304,358.9,304l-2.4-0.1l-10.8,1.5c-16.9,3.9-31,15.7-50.5,33.8c-25.2-14.7-52.4-37.6-68.7-54.3c-16.7-17.1-39.9-47.7-52.4-71.6c22-21.6,37.4-38.7,38.4-61.7c0-1-13.8-110.1-48.9-131.7l0,0l-5.1-3.1c-9.6-5.7-27.5-16.4-49.3-16.4c-5.4,0-10.8,0.7-17,2.3c-6.9,2-13.3,4.8-20,9.1C55.9,23,26.2,46.7,11.7,78c-13.5,30.8-4.4,187.9,113.4,311c111.6,116.8,241.2,122.7,266.1,122.7c6.4,0,15.1-0.3,22.4-1.6l2.8-0.1l6.7-2.5c32.2-13.2,56.9-41.7,68.4-57.2C518.4,415.5,497.8,376.6,490.9,363.4L490.9,363.4z M445.4,415.1c-10.5,14-27.3,31.3-42.6,38c-1.5,0.2-5.4,0.6-11.6,0.6c-20.7,0-128.8-5.1-224.1-104.8C67,244.3,62.6,119,65.5,100c6.6-12.7,21.2-27.7,38.7-39.8c0.5-0.3,1.9-1.1,3.4-1.6c5.5-1.4,15.6,4.6,21,7.8l2.4,1.5c8.1,13.5,20.6,63.6,23.3,81.2c-3.8,6.4-19.2,21.4-27.7,29.8l-1,1.1c-11.9,12.8-15.5,31.2-8.9,47.3c14.2,32.9,45.9,75.3,68.4,98.3c22.1,22.8,59.4,53.4,93.2,70.6c16.3,8.1,36.3,4.8,49.1-7.5c10.1-9.4,25-23.4,30.6-26.3c17.6,3.4,67.7,18.2,80.8,26.7l1.1,2C446.9,404.3,448.5,411,445.4,415.1L445.4,415.1z"></path>
  2. Replace this with a custom icon and give it the same ID (pencil). Use the below symbol for a fish icon.

    <symbol id="pencil" viewBox="0 26 100 48">
       <path d="M98.5,47.5C96.5,45.5,81,35,62,35c-2.1,0-4.2,0.1-6.2,0.3L39,26c0,4.5,1.3,9,2.4,12.1C31.7,40.7,23.3,44,16,44L0,34
       c19,0,34.5-10.5,36.5-12.5S100.5,49.5,98.5,47.5z M85.5,50c-1.4,0-2.5-1.1-2.5-2.5s1.1-2.5,2.5-2.5s2.5,1.1,2.5,2.5

Deploy the Sprite Map Client Extension

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 [email protected] and the password test. When prompted, change the password to learn.

Next, run this command from the client extension project’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 liferay-sample-theme-spritemap-1_1.0.0

Use the New Sprite Map on a Page


The theme sprite map client extension is currently behind a dev feature flag (LPS-166479). You must not use this client extension in production. Use it only for testing purposes.

Configure a page to use your deployed client extension:

  1. Go to the page, then click Edit (Edit icon) at the top.

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

  3. In the Theme Sprite Map Client Extension section, click Add (Add).

  4. Select the newly deployed sprite map, Liferay Sample Theme Spritemap 1.

    Select the Liferay Sample Theme Spritemap 1 client extension and click Save.

  5. Scroll down and click Save.

  6. Go back to the page. In the navbar, a fish icon has replaced the pencil (Edit icon) for the edit functionality.

The new icon from the sprite map appears on the navbar.

Next Steps

You have successfully used a theme sprite map client extension. Next, try deploying other client extension types.