When should I use the Custom Element client extension type?

• You want to ship a React / Vue / vanilla web component to Liferay pages. • You need per-page-instance widgets that users can add via the widget menu. • You already have a component and want to expose it inside DXP without writing a portlet.

How do I create a Custom Element client extension?

1. Build your component as an ES module that calls `customElements.define('my-tag', MyClass)`. 2. Deploy the built JS bundle behind `${portalURL}/o/ /index.js` (assemble it under `static/`). 3. Reference it in `urls:` and put the tag name in `htmlElementName:`. 4. Users add the widget from the widget menu; instances render your tag with a unique id.

What fields are required on a Custom Element client extension?

htmlElementName (string): The HTML tag Liferay renders on the page. urls (string[]): JS module URLs; at least one must define + register the element.

Custom Element

Embed a web component as a Liferay widget.

type: customElement·Frontend·Liferay docs →

at a glance

Custom Element (type: customElement) is a Liferay Client Extension in the Frontend category. Registers an HTML custom-element tag as a Liferay widget. Liferay handles the widget lifecycle, friendly URLs, and menu category; your extension only ships JS that defines the element and (optionally) CSS. Custom Element is the primary path to embedding modern web components — React, Vue, LitElement, Svelte, or vanilla `HTMLElement` classes — inside Liferay DXP without writing a portlet. Liferay renders your `<my-tag>` element on the page with a unique instance id per placement, so component state stays scoped to each widget instance. Widgets appear in Liferay's widget menu under the `portletCategoryName` you specify (default: `category.client-extensions`).

yaml type: customElement
category: Frontend
required fields: htmlElementName, urls
liferay docs: learn.liferay.com →

# description

Registers an HTML custom-element tag as a Liferay widget. Liferay handles the widget lifecycle, friendly URLs, and menu category; your extension only ships JS that defines the element and (optionally) CSS. Custom Element is the primary path to embedding modern web components — React, Vue, LitElement, Svelte, or vanilla `HTMLElement` classes — inside Liferay DXP without writing a portlet. Liferay renders your `<my-tag>` element on the page with a unique instance id per placement, so component state stays scoped to each widget instance. Widgets appear in Liferay's widget menu under the `portletCategoryName` you specify (default: `category.client-extensions`).

UI extensions that render on Liferay pages or modify page appearance.

# when to use

→You want to ship a React / Vue / vanilla web component to Liferay pages.
→You need per-page-instance widgets that users can add via the widget menu.
→You already have a component and want to expose it inside DXP without writing a portlet.

# how to use

01Build your component as an ES module that calls customElements.define('my-tag', MyClass).
02Deploy the built JS bundle behind ${portalURL}/o/<name>/index.js (assemble it under static/).
03Reference it in urls: and put the tag name in htmlElementName:.
04Users add the widget from the widget menu; instances render your tag with a unique id.

# required fields

field	type	description
`htmlElementName`required	`string`	The HTML tag Liferay renders on the page.
`urls`required	`string[]`	JS module URLs; at least one must define + register the element.

# optional fields

field	type	description
`name`	`string`	Display name in the widget menu.
`cssURLs`	`string[]`	CSS added to <head> when the widget is on the page.
`friendlyURLMapping`	`string`	Friendly-URL prefix for widget state.
`instanceable`	`boolean`	Allow multiple instances on the same page.
`portletCategoryName`	`string`	Category in the widget menu.
`properties`	`string[]`	Attributes to add to the rendered element, e.g. `["theme=dark"]`.
`useESM`	`boolean`	Load `urls` with `type="module"`.

# example

client-extension.yaml

my-widget:
    type: customElement
    name: My Widget
    htmlElementName: my-widget
    urls:
        - ${portalURL}/o/my-widget/index.js
    cssURLs:
        - ${portalURL}/o/my-widget/styles.css
    instanceable: false
    portletCategoryName: category.client-extensions
    useESM: true

# more in frontend

cd ..scaffold this type in VS Code →