Migration to UI5 Web Components 2.0
This guide will assist you in seamlessly transitioning from UI5 Web Components version 1.x to UI5 Web Components 2.0.
@ui5/webcomponents-base
UI5Element
- The
UI5Element#rendermethod has been removed in favor of theUI5Element#renderermethod.
If you previously used render:
class MyClass extends UI5Element {
static get render() {
return litRenderer;
}
}
Now use renderer instead:
class MyClass extends UI5Element {
static get renderer() {
return litRenderer;
}
}
StaticArea, StaticAreaItem
This change mainly manifests in component development.
There used to be a so-called "static area" (ui5-static-area) - a DOM element directly in the <body> where the popups of all components were placed. This guaranteed that even if the HTML document had overflow: hidden, transform, or similar CSS rules applied, or the component was in a stacking context, its popup would still be positioned correctly.
There is no longer a need for a "static area" since the browser now ensures the correct positioning of popups thanks to the popover API that is fully adopted by the UI5 Web Components.
- The
StaticAreahas been removed as it's unnecessary.
If you previously created a web component with a popup part, you had to define staticAreaTemplate and staticAreaStyles:
@customElement({
tag: "ui5-select",
template: SelectTemplate,
staticAreaTemplate: SelectPopoverTemplate,
styles: [
selectCss,
],
staticAreaStyles: [
selectPopoverCss,
],
)}
class Select extends UI5Element {
Now, remove the staticAreaTemplate and staticAreaStyles settings as the popup part is rendered inside the component's ShadowDOM and there is no template and style separation as before:
@customElement({
tag: "ui5-select",
template: SelectTemplate,
styles: [
selectCss,
],
)}
class Select extends UI5Element {
- The
UI5Element.getSaticAreaItemDomRefmethod has been removed as it's unnecessary.
If you previously accessed the component's popup part (for example the dropdown of Select) via the StaticArea:
const staticAreaItem = await this.getSaticAreaItemDomRef();
staticAreaItem.querySelector("ui5-responsive-popover");
Now query the popup from inside the component's ShadowDOM directly:
this.shadowRoot.querySelector("ui5-responsive-popover");
Decorators
These changes are related to the component development.
@property#defaultValue
The defaultValue field of the @property decorator has been removed. Providing initial (default) values for the properties used to be part of the @property decorator with a defaultValue field. The defaultValue used to have two mixed usages:
- to provide an initial value if none is given
- to provide a fallback value if an invalid value is given by the app developer (mostly for numbers and enum
If you have previously used the @property decorator and set the defaultValue field:
@property({ defaultValue: "abc" })
name!: string;
@property({ type: PageBackgroundDesign, defaultValue: PageBackgroundDesign.Solid })
backgroundDesign!: `${PageBackgroundDesign}`;
Now, component development is switching to the standard way of using property initializers:
-
Initial Values: they are no longer magically provided by the framework. Properties should be either optional or initialized, and very rarely (for complex objects) described as non-null
-
Fallback values: all runtime checks for properties (especially enumerations) are removed. All type-checking is left to the TypeScript compiler and assigning an invalid value to an enumeration or a number/boolean field is considered a bug that should be fixed, instead of the framework silently masking it by providing a fallback value.
- @property({ defaultValue: "abc" })
- name!: string;
+ @property()
+ name = "abc";
- @property({ type: PageBackgroundDesign, defaultValue: PageBackgroundDesign.Solid })
- backgroundDesign!: `${PageBackgroundDesign}`;
+ @property()
+ backgroundDesign: `${PageBackgroundDesign}` = "Solid";
@property({ type: Boolean })
- noScrolling!: boolean;
+ noScrolling = false;
@property#validator
- The
validatorfield of the@propertydecorator has been removed. You can use the newly introducedconverterfield to define how the framework should convert the attribute to the property and vice versa. It has the following signature:
converter?: {
fromAttribute(value: string | null, type: unknown): string | number | boolean | null | undefined,
toAttribute(value: unknown, type: unknown): string | null,
}
If you previously used validator: Integer:
@property({ validator: Integer, defaultValue: 0 })
progress!: number;
Now use type: Number instead:
converter?: {
@property({ type: Number })
progress = 0;
If you previously used validator: DOMReference:
converter?: {
@property({ validator: DOMReference, defaultValue: "" })
opener!: HTMLElement | string
Now use the converter instead:
@property({ converter: DOMReference })
opener?: HTMLElement | string;
Device
- The
Device#isIEmethod has been removed and is no longer available - the IE browser is not supported anymore.
CSP
- The
CSP.jsmodule has been removed and the creation of<style>and<link>tags, as all browsers now supportadoptedStyleSheetsandadoptedStyleSheetsas CSP-compliant by design.
If you previously imported:
import { setUseLinks } from "@ui5/webcomponents-base/dist/CSP.js"
import { setPackageCSSRoot } from "@ui5/webcomponents-base/dist/CSP.js"
import { setPreloadLinks } from "@ui5/webcomponents-base/dist/CSP.js"
Now remove the imports:
// The `adoptedStyleSheets` as CSP-compliant by design
InputElementsFormSupport
- The
@ui5/webcomponents-base/dist/features/InputElementsFormSupport.jsfeature has been removed. Previously, the feature was required to make all form-associated web components (CheckBox, Inpuit, Select, etc) work in HTML forms properly. Now, with adopting theElementInternals APIall form-associated web components work natively in HTML form elements.
If you previously imported:
import "@ui5/webcomponents-base/dist/features/InputElementsFormSupport.js";
Now remove the import as it's not available, but more importantly - it's unnecessary.
// All form elements work natively in HTML form elements
@ui5/webcomponents-theming
- The
Belizetheme has been removed and is no longer available
If you previously used Belize:
setTheme(“sap_belize”);
Now the framework will fallback to Horizon:
setTheme(“Belize”); // fallbacks to Horizon
@ui5/webcomponents
ui5-badge
- The Badge
ui5-badgehas been renamed to Tagui5-tag.
If you previously used the ui5-badge:
<ui5-badge></ui5-badge>
Now use ui5-tag instead:
<ui5-tag></ui5-tag>
-
The
designproperty has a new default valueNeutralinstead ofSet3.Set3is no longer a valid value for thedesignproperty. -
The
wrappintTypedefault value has been changed fromNonetoNormaland the Tag's text will wrap by default.
If you previously set wrapping-type="Normal":
<ui5-tag wrapping-type="Normal"></ui5-tag>
Now, it's not necessary and can be removed:
<ui5-tag></ui5-tag>
If you previously did not use the property at all:
<ui5-tag></ui5-tag>
Now, you need to set wrapping-type="None" to keep text truncating:
<ui5-tag wrapping-type="None"></ui5-tag>
ui5-breadcrumbs
- The
separator-styleproperty is renamed toseparatorsand theBreadcrumbsSeparatorStyleenum is renamed toBreadcrumbsSeparator.
If you previously used the separator-style property:
<ui5-breadcrumbs separator-style="Slash">
Now use separators instead:
<ui5-breadcrumbs separators="Slash">