Custom Element YAML Configuration Reference

You can define a custom element client extension with a client-extension.yaml file.

Usage Details

This client-extension.yaml file defines a custom element client extension:

able-custom-element:
    cssURLs:
        - style.css
    friendlyURLMapping: vanilla-counter
    htmlElementName: vanilla-counter
    instanceable: false
    name: Able Custom Element
    portletCategoryName: category.client-extensions
    type: customElement
    urls:
        - index.js
    useESM: false

The required urls property specifies one or more paths to JavaScript resources. One of these JavaScript resources must contain the custom element initialization code. The htmlElementName is required to define the custom element’s identifier in the page HTML.

The friendlyURLMapping property applies a prefix to the widget’s URL, defining a route for interactions with the element on the page. You can also use this mapping like a namespace to prevent conflicts when retrieving the custom element’s persisted state information. For example, to access a custom element with friendlyURLMapping set to welcome and using the alpha or beta routes, you can append /-/welcome/alpha or /-/welcome/beta to the URL.

The example workspace contains a complete custom element client extension.

YAML Properties

These properties are specific to custom element client extensions:

Name	Data Type	Default Value	Description
`cssURLs`	String[] (partial URLs)	`[]`	List of CSS paths added to the HTML head when the custom element is used on a page.
`friendlyURLMapping`	String		Mapping of a friendly URL prefix to the specific custom element widget.
`htmlElementName`	String		The HTML element name that refers to the custom element, which is rendered in the page markup.
`instanceable`	True/false	`false`	Whether the custom element widget can appear multiple times on a page.
`portletCategoryName`	String	`category.client-extensions`	The menu category of the custom element widget.
`properties`	String[]	`[]`	Properties to append as attributes to the custom HTML element. They use a newline as a separator and are processed as Java properties.
`urls`	String[] (partial URLs)		(Required) List of paths to JavaScript resources that are added to the HTML head when the widget is used on a page. One of these resources must contain the custom element initialization code. This combines with `baseURL` to form a complete URL.
`useESM`	True/false	`false`	Whether the JavaScript code uses ESM format. When `true`, the JavaScript is added to the page with the `type="module"` property.