To define your own web component, you need to:
- Use the
@customElement
decorator. - Extend the
UI5Element
base class.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
// class implementation
}
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
@customElement({
tag: "my-demo-component",
renderer: ...,
styles: ...,
template: ...,
dependencies: ...,
languageAware: ...,
themeAware: ...,
fastNavigation: ...,
formAssociated: ...,
shadowRootOptions: ...,
})
class MyDemoComponent extends UI5Element {
// class implementation
}
The customElement
decorator is a class decorator that takes one argument, which can be either a string or an object literal containing configuration options for the component. This allows each component to be individually configured.
When the argument is a string, it defines the tag name of the component. Otherwise, if the argument is an object literal you can see available options below.
This option is a string that sets the name of the custom element, registering the component within the global CustomElementsRegistry
, where all custom elements are defined.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
@customElement({
tag: "my-demo-component"
})
class MyDemoComponent extends UI5Element {
// class implementation
}
Note: As per the HTML specification, the tag name must contain a dash ('-').
This option specifies the rendering engine for the component. UI5 Web Components are agnostic of the DOM rendering engine used. However, all standard UI5 Web Components (@ui5/webcomponents
, @ui5/webcomponents-fiori
, etc.) use lit-html as the rendering technology of choice.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
@customElement({
renderer: litRender
})
class MyDemoComponent extends UI5Element {
// class implementation
}
This option accepts a template in a format that your defined renderer will understand.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import MyDemoComponentTemplate from "./generated/templates/MyDemoComponentTemplate.lit.js";
@customElement({
template: MyDemoComponentTemplate
})
class MyDemoComponent extends UI5Element {
// class implementation
}
Note: Standard UI5 Web Components use Handlebars templates that are automatically converted to lit-html
syntax by the build script. If you have a MyDemoComponentTemplate.hbs
, the build script will create a generated/templates/DemoTemplate.lit.ts
file for you.
This option accepts either component styles or an array of component styles that should be inserted inside the shadow root of the component.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import MyDemoComponentCss from "./generated/themes/MyDemoComponent.css.js";
@customElement({
styles: MyDemoComponentCss
})
class MyDemoComponent extends UI5Element {
// class implementation
}
Note: The build scripts automatically transpile your .css
files to JavaScript files. For example, your my-package/src/theme/MyDemoComponent.css
will be transpiled to my-package/src/generated/themes/MyDemoComponent.css.ts
, which, in addition to your component's CSS, also contains definitions for all CSS variables for the default theme.
This option accepts an array of dependencies, which are all other web components used inside the .hbs
template file. Without this, the internally used web components won't be defined.
Furthermore, to utilize the Scoping feature, you must list all the internally used web components in the dependencies
static getter. The framework reads the dependencies and scopes the tag names of the listed web components.
For example, if the ui5-icon
tag (or any other standard or custom UI5 Web Component) is used inside the template, you must import the Icon
web component and add it to the dependencies
static getter as shown:
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import Icon from "@ui5/webcomponents/dist/Icon.js";
@customElement({
dependencies: [Icon]
})
class MyDemoComponent extends UI5Element {
// class implementation
}
This option accepts a boolean value and determines if the component should be re-rendered whenever the language changes. Use this setting if your component has translatable texts and needs to be re-rendered when the app changes the language.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
@customElement({
languageAware: true
})
class MyDemoComponent extends UI5Element {
// class implementation
}
This option accepts a boolean value and determines if the component should be re-rendered whenever the theme changes.
Important: You should almost never use this setting.
Components are usually built so that their HTML and CSS are the same for all themes, with only CSS variables changing. This way, the browser automatically updates the styles when the CSS variables get new values.
However, in rare cases, a component must behave differently (not just look differently) based on the theme. For example, the ui5-icon
component shows different versions of the icons based on the theme. Use the themeAware
setting in these exceptional cases to ensure your component is re-rendered on theme change.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
@customElement({
themeAware: true
})
class MyDemoComponent extends UI5Element {
// class implementation
}
This option accepts a boolean value and defines whether this control supports F6 fast navigation. When enabled, the framework will set the data-sap-ui-fastnavgroup
attribute on the component's root element to construct a fast navigation group.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
@customElement({
fastNavigation: true
})
class MyDemoComponent extends UI5Element {
// class implementation
}
This option accepts a boolean value and defines if the component should support native form functionality. When set, the framework uses the ElementInternals
API to implement the required interfaces for the component to work in a native HTML form as standard HTML input elements do. This is commonly used in input-type components such as Input, ComboBox, MultiComboBox, Select, and others.
import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
@customElement({
formAssociated: true
})
class MyDemoComponent extends UI5Element {
// class implementation
}
By following these guidelines, you can define and configure custom UI5 web components to meet your specific requirements.