Using Routes with Custom Elements

Liferay 7.4+

Custom element client extensions use Liferay’s frontend infrastructure to register external applications with the Liferay platform and render them as widgets. For applications that include multiple routes (e.g., React Router), you can define remote application properties to determine which routes are used for a widget at runtime. These properties can be set for an application via the Remote Apps menu in Liferay or the widget’s configuration options once deployed.

Warning

Deploying Custom elements or IFrames like other types of client extensions is a beta feature in Liferay 7.4. This tutorial deploys custom element remote applications differently, and it is still the recommended approach until a future update.

In this tutorial, create a basic React application using Liferay’s create_custom_element.sh script, which generates a sample app with three routes: hello-world, hello-foo, hello-bar. After compiling the application and hosting its .js and .css files, register the application with Liferay and deploy it as a page widget. Finally, configure it to use each of the alternative routes.

Note

Custom element client extensions can use any technology, regardless of how it’s built, packaged, or hosted. This tutorial only offers a sample custom element application with basic routing.

Running create_custom_element.sh requires the latest versions of Node.JS, NPM, and YARN. Before proceeding, ensure these tools are installed.

Creating, Building, and Hosting the React Application

1. Start a new Liferay DXP 7.4+ container. You can continue to the next steps while the container starts.

   docker run -it -m 8g -p 8080:8080 liferay/dxp:2025.q1.6-lts
   

2. Run this command in a separate terminal to generate the React application.

   curl -Ls https://github.com/liferay/liferay-portal/raw/master/tools/create_custom_element.sh | bash -s j1v3-custom-element react
   

3. Verify the application was created successfully.

   The script creates a new React application called j1v3-custom-element with these elements:

   j1v3-custom-element
   ├── node_modules
   ├── README.md
   ├── package.json
   ├── public
   │   └── index.html
   ├── src
   │   ├── common
   │   │   ├── services
   │   │   │   └── liferay
   │   │   │       ├── api.js
   │   │   │       └── liferay.js
   │   │   └── styles
   │   │       ├── hello-world.scss
   │   │       ├── index.scss
   │   │       └── variables.scss
   │   ├── index.js
   │   └── routes
   │       ├── hello-bar
   │       │   └── pages
   │       │       └── HelloBar.js
   │       ├── hello-foo
   │       │   └── pages
   │       │       └── HelloFoo.js
   │       └── hello-world
   │           └── pages
   │               └── HelloWorld.js
   └── yarn.lock
   

4. Navigate to the new j1v3-custom-element folder and build the application.

   cd j1v3-custom-element
   

   yarn build
   

5. Verify the build succeeded and note the application’s .js and .css files.

   Creating an optimized production build...
   Compiled successfully.
   
   File sizes after gzip:
   
   43.51 kB  build/static/js/main.114dde4a.js
   121 B     build/static/css/main.9877909d.css
   

6. Sign in to Liferay at <http://localhost:8080> using the email address [e-mail] and the password test. When prompted, change the password to learn.

7. Open the Site Menu (), expand Content & Data, and go to Documents and Media.

8. Click Add () and select Multiple Files Upload.

9. Drag and drop the .js and .css files into the upload area.

   

10. Click Publish.

This adds the files to the Liferay Document Library and assigns them unique WebDAV URLs, which you use to create the remote application.

Tip

This tutorial hosts the application’s static resources in Liferay’s Document Library for demonstration purposes. In a production environment, you should host the application’s files on a server optimized for hosting static resources.

To view each file’s URL, click the Info icon () and select one of the files at a time. Copy each file’s WebDAV URL and save them for use in the next step.

For example,

• http://localhost:8080/webdav/guest/document_library/main.114dde4a.js
• http://localhost:8080/webdav/guest/document_library/main.9877909d.css

Registering and Deploying the Application

1. Open the Global Menu (), click on the Applications tab, and go to Remote Apps.

2. Click Add ().

3. Enter these values:

   Field	Value
   Name	J1V3-Custom-Element
   Type	Custom Element
   HTML Element Name	j1v3-custom-element
   URL	WebDAV URL for the .js file
   CSS URL	WebDAV URL for the .css file
   Instanceable	✔
   Portlet Category Name	Remote Apps

4. Click Save.

Once saved, Liferay creates a widget named J1V3-Custom-Element, which you can deploy to Site Pages like any other Page widget. It appears under the selected Portlet Category Name.

Since J1V3-Custom-Element is instanceable, you can add many of them to a page, each with its own independent configuration. For this example, add the widget to a page twice.

Using the route Property

The auto-generated app includes three routes: hello-world, hello-foo, hello-bar. By default the application uses the hello-world route. However, you can use remote application properties to configure it to use an alternate route. You can set these properties via the Remote Apps menu or a widget’s configuration options.

Defining a Route Property via the Remote Apps Menu

1. Open the Global Menu (), click on the Applications tab, and go to Remote Apps.

2. Select J1V3-Custom-Element.

   

3. Enter route=hello-foo into the Properties field.

   

4. Click Publish.

5. Verify both deployed widgets use the HelloFoo route.

   

Defining a Route Property via Widget Configuration

1. Edit the Page containing the J1V3-Custom-Element widgets.

2. Click Options () in the widget header → Configuration.

   

   Note

   Before Liferay DXP 2025.Q1/Portal GA132, the Configuration option appeared in the widget’s top-right corner.

3. Enter route=hello-bar into the Properties field.

   

4. Click Save.

5. Verify the configured widget uses the hello-bar route, while the other widget still uses the hello-foo route.

   

Analyzing the Route Code

import React from 'react';
import {createRoot} from 'react-dom/client';

import api from './common/services/liferay/api';
import {Liferay} from './common/services/liferay/liferay';
import HelloBar from './routes/hello-bar/pages/HelloBar';
import HelloFoo from './routes/hello-foo/pages/HelloFoo';
import HelloWorld from './routes/hello-world/pages/HelloWorld';

import './common/styles/index.scss';

const App = ({route}) => {
	if (route === 'hello-bar') {
		return <HelloBar />;
	}

	if (route === 'hello-foo') {
		return <HelloFoo />;
	}

	return (
		<div>
			<HelloWorld />
		</div>
	);
};

class WebComponent extends HTMLElement {
	constructor() {
		super();
	}

	connectedCallback() {
		createRoot(this).render(
			<App
				route={this.getAttribute('route')}
			/>,
			this
		);

		if (Liferay.ThemeDisplay.isSignedIn()) {
			api('o/headless-admin-user/v1.0/my-user-account')
				.then((response) => response.json())
				.then((response) => {
					if (response.givenName) {
						const nameElements = document.getElementsByClassName(
							'hello-world-name'
						);

						if (nameElements.length) {
							nameElements[0].innerHTML = response.givenName;
						}
					}
				});
		}
	}
}

const ELEMENT_ID = 'j1v3-custom-element';

if (!customElements.get(ELEMENT_ID)) {
	customElements.define(ELEMENT_ID, WebComponent);
}

This index.js file creates the WebComponent class, which extends the HTMLElement interface. This class implements the interface’s connectedCallback() function, which calls ReactDOM.render with App as a parameter. When App is called, it checks for any defined "route" attribute and compares that value with the available routes. If it matches either hello-foo or hello-bar, it returns and renders the corresponding route. Otherwise, it returns and renders hello-world.

Each of the routes is imported into the index.js file from the routes folder:

routes
├── hello-bar
│   └── pages
│       └── HelloBar.js
├── hello-foo
│   └── pages
│       └── HelloFoo.js
└── hello-world
    └── pages
        └── HelloWorld.js

HelloWorld.js

const HelloWorld = () => (
	<div className="hello-world">
		<h1>
			Hello <span className="hello-world-name">World</span>
		</h1>
	</div>
);

HelloFoo.js

const HelloFoo = () => (
	<div className="hello-foo">
		<h1>Hello Foo</h1>
	</div>
);

HelloBar.js

const HelloBar = () => (
	<div className="hello-bar">
		<h1>Hello Bar</h1>
	</div>
);

Related Topics

• Customizing Liferay’s Look and Feel
• Integrating External Applications
• Creating a Basic Custom Element
• Client Extensions UI Reference