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">
ui5-busy-indicator
- The
sizeproperty now accepts different values. If you previously used it like:
<ui5-busy-indicator size="Small"></ui5-busy-indicator>
Now use the new values instead:
<ui5-busy-indicator size="S"></ui5-busy-indicator>
ui5-button
- The boolean property
iconEndthat used to define the placement of the icon (to the start or to the end) has been replaced by the the string propertyendIcon, defining the icon, displayed at the end.
If you previously set icon and icon-end to display an icon after the Button's text:
<ui5-button icon="home" icon-end>Button</ui5-button>
Now, you must use the new property:
<ui5-button end-icon="home">Button</ui5-button>
Furthermore, this allows the displaying of two icons - to the start and to the end:
<ui5-button icon="employee" end-icon="home">Button</ui5-button>
ui5-calendar
-
The event
selected-dates-changeis renamed toselection-change. In addition the event detailsvaluesanddatesare renamed toselectedValuesandselectedDateValues.If you previously used the Calendar event as follows:
myCalendar.addEventListener("selected-dates-change", () => {
const values = e.detail.values;
const dates = e.detail.dates;
})
Now you have to use the new event name and details:
myCalendar.addEventListener("selection-change", () => {
const values = event.detail.selectedValues;
const dates = event.detail.selectedDateValues;
})
- The
datesslot in the Calendar now works with aui5-date-rangewhenselection-mode="Range". If you previously defined date ranges as follows:
<ui5-calendar selection-mode="Range">
<ui5-date value="Jan 20, 2021"></ui5-date>
<ui5-date value="Jan 30, 2021"></ui5-date>
</ui5-calendar>
Now, they are declared using the ui5-date-range:
<ui5-calendar selection-mode="Range">
<ui5-date-range start-value="Jan 20, 2021" end-value="Jan 30, 2021"></ui5-date-range>
</ui5-calendar>
ui5-card
- The
ICardHeaderinterface has been removed.
If you previously used the interface
import type { ICardHeader } from "@ui5/webcomponents-base/dist/Card.js"
Use the CardHeader type instead:
import type CardHeader from "@ui5/webcomponents-base/dist/CardHeader.js"
ui5-card-header
- The
statusproperty and its shadow part have been renamed.
If you previously used them:
<style>
.cardHeader::part(status) { ... }
</style>
<ui5-card-header status="3 of 10"></ui5-popover>
Now use additionalText instead:
<style>
.cardHeader::part(additional-text) { ... }
</style>
<ui5-card-header class="cardHeader" additional-text="3 of 10"></ui5-card-header>
ui5-carousel
- The
pageIndicatorStyleis no longer exists.
If you previously used it like:
<ui5-carousel page-indicator-style="Numeric"></ui5-carousel>
Now you should use pageIndicatorType instead:
<ui5-carousel page-indicator-type="Numeric"></ui5-carousel>
- Properties
items-per-page-s,items-per-page-m,items-per-page-lare replaced by a single propertyitems-per-page, which also addsXLsize
If previously you have used:
<ui5-carousel items-per-page-s="3" items-per-page-m="3" items-per-page-l="3">
Now use:
<ui5-carousel items-per-page="S3 M3 L3 XL3">
ui5-color-palette-popover
- The
openPopoverandshowAtmethods are removed in favor ofopenandopenerproperties.
If you previously used the imperative API:
button.addEventListener("click", function(event) {
colorPalettePopover.showAt(this);
});
Now the declarative API should be used instead:
<ui5-button id="opener">Open</ui5-button>
<ui5-color-palette-popover opener="opener">
button.addEventListener("click", function(event) {
colorPalettePopover.open = !colorPalettePopover.open;
});
ui5-color-picker
- The property
coloris renamed tovalue.
If you previously used the change event of the ColorPicker as follows:
<ui5-color-picker color="red"></ui5-color-picker>
Now you have to use it like this:
<ui5-color-picker value="red"></ui5-color-picker>
ui5-checkbox
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-checkbox value-state="Error"></ui5-checkbox>
<ui5-checkbox value-state="Warning"></ui5-checkbox>
<ui5-checkbox value-state="Success"></ui5-checkbox>
Now you have to use it like:
<ui5-checkbox value-state="Negative"></ui5-checkbox>
<ui5-checkbox value-state="Critical"></ui5-checkbox>
<ui5-checkbox value-state="Positive"></ui5-checkbox>
- The
wrappintTypedefault value has been changed fromNonetoNormaland the CheckBox text will wrap by default.
If you previously set wrapping-type="Normal":
<ui5-checkbox wrapping-type="Normal"></ui5-checkbox>
Now, it's unnecessary and can be removed as the text will wrap by default:
<ui5-checkbox></ui5-checkbox>
If you previously did not use the property at all:
<ui5-checkbox></ui5-checkbox>
Now, you need to set wrapping-type="None" to keep the text truncating:
<ui5-checkbox wrapping-type="None"></ui5-checkbox>
ui5-combobox
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-combobox value-state="Error"></ui5-combobox>
<ui5-combobox value-state="Warning"></ui5-combobox>
<ui5-combobox value-state="Success"></ui5-combobox>
Now you have to use it like:
<ui5-combobox value-state="Negative"></ui5-combobox>
<ui5-combobox value-state="Critical"></ui5-combobox>
<ui5-combobox value-state="Positive"></ui5-combobox>
- The
ui5-cb-group-itemweb component has been replaced byui5-cb-item-group. Furthermore, grouping is now implemented with a hierarchical structure, e.g. nesting.
If you previously used the ui5-cb-group-item web component as separator to define groups in a flat structure:
<ui5-combobox placeholder="Select a country">
<ui5-cb-group-item text="Asia"></ui5-cb-group-item>
<ui5-cb-item text="Afghanistan"></ui5-cb-item>
<ui5-cb-item text="China"></ui5-cb-item>
<ui5-cb-group-item text="Europe"></ui5-cb-group-item>
<ui5-cb-item text="Austria"></ui5-cb-item>
<ui5-cb-item text="Bulgaria"></ui5-cb-item>
</ui5-combobox>
Now use the ui5-cb-item-group web component and nest ui5-cb-item web components inside to form a group
in a hierarchical structure:
<ui5-combobox placeholder="Select a country">
<ui5-cb-item-group header-text="Asia">
<ui5-cb-item text="Algeria"></ui5-cb-item>
</ui5-cb-item-group>
<ui5-cb-item-group header-text="Europe">
<ui5-cb-item text="Austria"></ui5-cb-item>
</ui5-cb-item-group>
</ui5-combobox>
ui5-cb-group-item
Previously:
import "@ui5/webcompoennts/dist/ComboBoxGroupItem.js"
<ui5-cb-group-item text="Asia"></ui5-cb-group-item>
Now:
import "@ui5/webcompoennts/dist/ComboBoxItemGroup.js"
<ui5-cb-item-group header-text="Asia">
<ui5-cb-item text="Algeria"></ui5-cb-item>
</ui5-cb-item-group>
ui5-date-picker
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-date-picker value-state="Error"></ui5-date-picker>
<ui5-date-picker value-state="Warning"></ui5-date-picker>
<ui5-date-picker value-state="Success"></ui5-date-picker>
Now you have to use it like:
<ui5-date-picker value-state="Negative"></date-picker>
<ui5-date-picker value-state="Critical"></date-picker>
<ui5-date-picker value-state="Positive"></ui5-date-picker>
- The methods
openPicker(),closePicker()andisOpen()are replaced byopenproperty.
If you previously used openPicker(), closePicker() or isOpen:
const datePicker = document.getElementById("exampleID");
datePicker.openPicker();
datePicker.closePicker();
Now use the open property instead:
const datePicker = document.getElementById("exampleID");
datePicker.open = true;
datePicker.open = false;
ui5-date-time-picker
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-datetime-picker value-state="Error"></ui5-datetime-picker>
<ui5-datetime-picker value-state="Warning"></ui5-datetime-picker>
<ui5-datetime-picker value-state="Success"></ui5-datetime-picker>
Now you have to use it like:
<ui5-datetime-picker value-state="Negative"></ui5-datetime-picker>
<ui5-datetime-picker value-state="Critical"></ui5-datetime-picker>
<ui5-datetime-picker value-state="Positive"></ui5-datetime-picker>
- The methods
openPicker(),closePicker()andisOpen()are replaced byopenproperty.
If you previously used openPicker(), closePicker() or isOpen:
const datetimePicker = document.getElementById("exampleID");
datetimePicker.openPicker();
datetimePicker.closePicker();
Now use the open property respectively:
const datetimePicker = document.getElementById("exampleID");
datetimePicker.open = true;
datetimePicker.open = false;
ui5-daterange-picker
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-daterange-picker value-state="Error"></ui5-daterange-picker>
<ui5-daterange-picker value-state="Warning"></ui5-daterange-picker>
<ui5-daterange-picker value-state="Success"></ui5-daterange-picker>
Now you have to use it like:
<ui5-daterange-picker value-state="Negative"></ui5-daterange-picker>
<ui5-daterange-picker value-state="Critical"></ui5-daterange-picker>
<ui5-daterange-picker value-state="Positive"></ui5-daterange-picker>
- The methods
openPicker(),closePicker()andisOpen()are replaced byopenproperty.
If you previously used openPicker(), closePicker() or isOpen:
const dateRangePicker = document.getElementById("exampleID");
dateRangePicker.openPicker();
dateRangePicker.closePicker();
Now use the open property respectively:
const dateRangePicker = document.getElementById("exampleID");
dateRangePicker.open = true;
dateRangePicker.open = false;
ui5-dialog
- The
showandclosepublic methods have been removed. Use the public propertyopeninstead.
If you previously used:
dialog.show();
...
dialog.close();
use the open property instead:
dialog.open = true;
...
dialog.open = false;
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-dialog state="Error"></ui5-dialog>
<ui5-dialog state="Warning"></ui5-dialog>
<ui5-dialog state="Success"></ui5-dialog>
Now you have to use it like:
<ui5-dialog state="Negative"></ui5-dialog>
<ui5-dialog state="Critical"></ui5-dialog>
<ui5-dialog state="Positive"></ui5-dialog>
- Methods
isOpenandcloseare no longer present. Nowopenproperty can be used instead.
Previously:
let isOpen = dialog.isOpen();
dialog.close();
Now:
let isOpen = dialog.open;
dialog.open = false;
- Method
showis no longer present. Useopenproperty instead.
Previously:
dialog.show();
Now:
dialog.open = true;
- Parameter
preventInitialFocusfrom methodshowis added as a property.
Previously:
dialog.show(true);
Now:
dialog.preventInitalFocus = true;
dialog.open = true;
- The events
after-closeandafter-openhave been renamed toopenandcloserespectively.
If you previously used the events like:
popover.addEventListener("after-open", (event) => {
});
popover.addEventListener("after-close", (event) => {
});
Now, you must use the new names:
popover.addEventListener("open", (event) => {
});
popover.addEventListener("close", (event) => {
});
ui5-file-uploader
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-file-uploader value-state="Error"></ui5-file-uploader>
<ui5-file-uploader value-state="Warning"></ui5-file-uploader>
<ui5-file-uploader value-state="Success"></ui5-file-uploader>
Now you have to use it like:
<ui5-file-uploader value-state="Negative"></ui5-file-uploader>
<ui5-file-uploader value-state="Critical"></ui5-file-uploader>
<ui5-file-uploader value-state="Positive"></ui5-file-uploader>
ui5-icon
- The properties
interactiveandaccessibleRolehave been removed and replaced by propertymodewith the following values Image(default): the icon will haverole="img".Interactive: the icon will haverole="button"and focus and press handling to enhance interactivity.Decorative: the icon will haverole="presentation"andaria-hidden="true", making it purely decorative without semantic content or interactivity.
If you previously used it like:
<ui5-icon name="home" accessible-role="img"></ui5-icon>
<ui5-icon name="home" interactive></ui5-icon>
<ui5-icon name="home" accessible-role="presentation" aria-hidden="true"></ui5-icon>
Now use the new mode property instead:
<ui5-icon name="home" mode="Image" ></ui5-icon>
<ui5-icon name="home" mode="Interactive"></ui5-icon>
<ui5-icon name="home" mode="Decorative"></ui5-icon>
ui5-input
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-input value-state="Error"></ui5-input>
<ui5-input value-state="Warning"></ui5-input>
<ui5-input value-state="Success"></ui5-input>
Now you have to use it like:
<ui5-input value-state="Negative"></ui5-input>
<ui5-input value-state="Critical"></ui5-input>
<ui5-input value-state="Positive"></ui5-input>
- The
openPickermethod has been removed and replaced by theopenproperty.
If you previously used the openPicker() method to open the Input suggestions:
input.openPicker();
Now, you must use the open property
input.open = true;
- The
suggestion-item-previewevent has been renamed toselection-change
If you previously attached to the suggestion-item-preview event:
input.addEventListener("suggestion-item-preview", event => { const { item, targetRef } = event.detail;});
Now you should attach to the selection-change event:
input.addEventListener("selection-change", event => { const { item, targetRef } = event.detail;});
Note: The event details remain the same. The only difference is that item and targetRef may be null, because the selection-change event is also fired when the input value no longer matches a selected suggestion.
- The
suggestion-item-selectevent has been removed.
If you previously attached to the suggestion-item-select event to detect which suggestion item has been selected by the user:
input.addEventListener("suggestion-item-select", event => {
const suggestionItem = event.detail.item;
});
Now, attach to the selection-change event to get the selected item the change event
to check if the input value matches the selected item:
let suggestionItem;
input.addEventListener("selection-change", (event) => {
suggestionItem = event.detail.item;
});
input.addEventListener("change", (event) => {
if(event.target.value && suggestionItem &&
(event.target.value === suggestionItem.text)){
// do something with the suggestion item
console.log(suggestionItem);
}
});
The property previewItem, which returned the current suggestion item on preview, is no longer present. The user can listen to the selection-change event to understand which suggestion item is on the preview.
- The read-only property
previewItemhas been removed
If you previously used the previewItem read-only property to get the suggestion item under preview:
const suggestionItemOnPreview = input.previewItem;
Now, attach to the selection-change to get the previewed suggestion item:
input.addEventListener("selection-change", event => {
const suggestionItemOnPreview = event.detail.item;
});
ui5-suggestion-item
- The properties
type,description,icon,iconEnd,image, andadditionalTextStatehave been removed in favor of the newly introducedui5-suggestion-item-customweb component that allows user-defined content.
If you previously used the ui5-suggestion-item web component and any of the removed properties:
<ui5-input show-suggestions>
<ui5-suggestion-item icon="home" description="my description"></ui5-suggestion-item>
</ui5-input>
Now use ui5-suggestion-item-custom web component with user-defined content and styles, for exmaple:
<style>
.content {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
height: 100%;
}
.titles {
display: flex;
flex-direction: column;
}
.green {
color: green;
}
</style>
<ui5-input show-suggestions>
<ui5-suggestion-item-custom>
<div class="content">
<ui5-icon name="globe"></ui5-icon>
<div class='titles'>
<span>${generateHighlightedMarkup(country, value)}</span>
<small>EU</small>
</div>
<span class='green'><b>EU</b></span>
</div>
</ui5-suggestion-item-custom>
</ui5-input>
ui5-suggestion-group-item
- The
ui5-suggestion-group-itemweb component has been replaced byui5-suggestion-item-group. Furthermore, grouping is now implemented with a hierarchical structure, e.g. nesting.
If you previously used ui5-suggestion-group-item web component as a separator in a flat structure:
import "@ui5/webcomponents/dist/SuggestionGroupItem.js";
<ui5-input show-suggestions>
<ui5-suggestion-group-item text="Group">
<ui5-suggestion-item text="Group Item 1"></ui5-suggestion-item>
<ui5-suggestion-item text="Group Item 2"></ui5-suggestion-item>
</ui5-input>
Now use the ui5-suggestion-item-group web component and nest ui5-suggestion-item web components inside:
import "@ui5/webcomponents/dist/SuggestionItemGroup.js";
<ui5-input show-suggestions>
<ui5-suggestion-item-group header-text="Group">
<ui5-suggestion-item text="Group Item 1"></ui5-suggestion-item>
<ui5-suggestion-item text="Group Item 2"></ui5-suggestion-item>
</ui5-suggestion-item-group>
</ui5-input>
ui5-multi-combobox
- The
open-changeevent has been replaced byopenandcloseevents, fired when the dropdown is opened or closed.
If you previously listened for open-change:
input.addEventListener("open-change", (event) => {});
Now, you must attach for open and close events:
input.addEventListener("open", (event) => {});
input.addEventListener("close", (event) => {});
- The
ui5-mcb-group-itemcomponent has been replaced byui5-mcb-item-group. Furthermore, grouping is now implemented with a hierarchical structure, e.g. nesting.
If you previously used the ui5-mcb-group-item web component as a separator to define groups in a flat structure:
<ui5-multi-combobox placeholder="Select a country">
<ui5-mcb-group-item text="Asia"></ui5-mcb-group-item>
<ui5-mcb-item text="Afghanistan"></ui5-mcb-item>
<ui5-mcb-item text="China"></ui5-mcb-item>
<ui5-mcb-group-item text="Europe"></ui5-mcb-group-item>
<ui5-mcb-item text="Austria"></ui5-mcb-item>
<ui5-mcb-item text="Bulgaria"></ui5-mcb-item>
</ui5-multi-combobox>
Now, you must use the ui5-mcb-item-group web component and nest ui5-mcb-item web components inside to form a group
in a hierarchical structure:
<ui5-multi-combobox placeholder="Select a country">
<ui5-mcb-item-group text="Asia">
<ui5-mcb-item text="Afghanistan"></ui5-mcb-item>
<ui5-mcb-item text="China"></ui5-mcb-item>
</ui5-mcb-item-group>
<ui5-mcb-item-group text="Europe">
<ui5-mcb-item text="Austria"></ui5-mcb-item>
<ui5-mcb-item text="Bulgaria"></ui5-mcb-item>
</ui5-mcb-item-group>
</ui5-multi-combobox>
- The
allowCustomValuesproperty has been renamed tonoValidation.
If you previously used the allowCustomValues property:
<ui5-multi-combobox allow-custom-values></ui5-multi-combobox>
Now use noValidation instead:
<ui5-multi-combobox no-validation></ui5-multi-combobox>
ui5-multi-input
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-multi-input value-state="Error"></ui5-multi-input>
<ui5-multi-input value-state="Warning"></ui5-multi-input>
<ui5-multi-input value-state="Success"></ui5-multi-input>
Now you have to use it like:
<ui5-multi-input value-state="Negative"></ui5-multi-input>
<ui5-multi-input value-state="Critical"></ui5-multi-input>
<ui5-multi-input value-state="Positive"></ui5-multi-input>
- The
openPickermethod has been removed and replaced by theopenproperty.
If you previously used the openPicker() method to open the MultiInput suggestions:
multiInput.openPicker();
Now, you must use the open property
multiInput.open = true;
- The
suggestion-item-previewevent has been renamed toselection-change
If you previously attached to the suggestion-item-preview event:
multiInput.addEventListener("suggestion-item-preview", event => { const { item, targetRef } = event.detail;});
Now you should attach to the selection-change event:
multiInput.addEventListener("selection-change", event => { const { item, targetRef } = event.detail;});
Note: The event details remain the same. The only difference is that item and targetRef may be null, because the selection-change event is also fired when the multiInput value no longer matches a selected suggestion.
- The
suggestion-item-selectevent has been removed.
If you previously attached to the suggestion-item-select event to detect which suggestion item has been selected by the user:
multiInput.addEventListener("suggestion-item-select", event => {
const suggestionItem = event.detail.item;
});
Now, attach to the selection-change event to get the selected item the change event
to check if the multiInput value matches the selected item:
let suggestionItem;
multiInput.addEventListener("selection-change", (event) => {
suggestionItem = event.detail.item;
});
multiInput.addEventListener("change", (event) => {
if(event.target.value && suggestionItem &&
(event.target.value === suggestionItem.text)){
// do something with the suggestion item
console.log(suggestionItem);
}
});
The property previewItem, which returned the current suggestion item on preview, is no longer present. The user can listen to the selection-change event to understand which suggestion item is on the preview.
- The read-only property
previewItemhas been removed
If you previously used the previewItem read-only property to get the suggestion item under preview:
const suggestionItemOnPreview = multiInput.previewItem;
Now, attach to the selection-change to get the previewed suggestion item:
multiInput.addEventListener("selection-change", event => {
const suggestionItemOnPreview = event.detail.item;
});
ui5-menu
- The
busyandbusyDelayhave been renamed toloadingandloadingDelay.
If you previously used the busy, busyDelay properties:
<ui5-menu header-text="My ui5-menu" busy busy-delay="100"><ui5-menu>
Now use loading and loadingDelay instead:
<ui5-menu header-text="My ui5-menu" loading loading-delay="100"><ui5-menu>
- Event names
after-closeandafter-openhave been renamedopenandclose.
If previously subscribed to the events as follows:
menu.addEventListener("after-open", function() {
});
menu.addEventListener("after-close", function() {
});
Now use the new event names instead:
menu.addEventListener("open", function() {
});
menu.addEventListener("close", function() {
});
ui5-menu-item
- The
startsSectionproperty has been removed and replaced by a separator web componentui5-menu-separator.
If you previously used startsSection to identify the ui5-menu-item starts new section and draw a line before it:
<ui5-menu>
<ui5-menu-item text="Item A"></ui5-menu-item>
<ui5-menu-item text="Item B" starts-section></ui5-menu-item>
</ui5-menu>
Now, you can use the ui5-menu-separator as a regular item inside the ui5-menu:
<ui5-menu>
<ui5-menu-item text="Item A"></ui5-menu-item>
<ui5-menu-separator></ui5-menu-separator>
<ui5-menu-item text="Item B"></ui5-menu-item>
</ui5-menu>
- The
busyandbusyDelayhave been renamed toloadingandloadingDelay.
If you previously used the busy and busyDelay properties:
<ui5-menu-item text="Open" icon="open-folder" busy busy-delay="100"><ui5-menu-item
Now use loading and loadingDelay instead:
<ui5-menu-item text="Open" icon="open-folder" loading loading-delay="100"><ui5-menu-item>
ui5-message-strip
- The property values
Warningare renamed toCritical. If you previously used it like:
<ui5-message-strip design="Warning"></ui5-message-strip>
Now you have to use it like:
<ui5-message-strip design="Critical"></ui5-message-strip>
ui5-label
- The
wrappintTypedefault value has been changed fromNonetoNormaland the Label will wrap by default.
If you previously set wrapping-type="Normal":
<ui5-label wrapping-type="Normal"></ui5-label>
Now, it's unnecessary and can be removed as the text will wrap by default:
<ui5-label></ui5-label>
If you previously did not use the property at all:
<ui5-label></ui5-label>
Now, you need to set wrapping-type="None" to keep the text truncating:
<ui5-label wrapping-type="None"></ui5-label>
ui5-li
- The web component class has been renamed from
StandardListItemtoListItemStandard.
If you previously imported the class as follows:
import StandardListItem from "@ui5/webcomponents/StandardListItem.js";
Now, change the import to:
import ListItemStandard from "@ui5/webcomponents/ListItemStandard.js";
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-li highlight="Error"></ui5-li>
<ui5-li highlight="Warning"></ui5-li>
<ui5-li highlight="Success"></ui5-li>
Now you have to use it like:
<ui5-li highlight="Negative"></ui5-li>
<ui5-li highlight="Critical"></ui5-li>
<ui5-li highlight="Positive"></ui5-li>
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-li additional-text-state="Error"></ui5-li>
<ui5-li additional-text-state="Warning"></ui5-li>
<ui5-li additional-text-state="Success"></ui5-li>
Now you have to use it like:
<ui5-li additional-text-state="Negative"></ui5-li>
<ui5-li additional-text-state="Critical"></ui5-li>
<ui5-li additional-text-state="Positive"></ui5-li>
- The
imageproperty has been removed and theimageContentslot has been renamed toimage.
If you previously used the image property:
<ui5-li image="./img/HT-1022.jpg">Standard List Item</ui5-li>
or the imageContent slot:
<ui5-li> Avatar inside imageContent slot
<ui5-avatar slot="imageContent" shape="Square" initials="ABC" color-scheme="Accent2"></ui5-avatar>
</ui5-li>
Now use the image slot instead:
<ui5-li> Avatar inside image slot
<img src="" slot="image" />
</ui5-li>
-
The
accessibleRoleproperty has been updated from a string type to an enum typeListItemAccessibleRole. The available options for theui5-li: -
ListItem- Represents the ARIA role "listitem". (by default) -
MenuItem- Represents the ARIA role "menuitem". -
TreeItem- Represents the ARIA role "treeitem". -
Option- Represents the ARIA role "option". -
None- Represents the ARIA role "none".
If you previously used the lowercase values:
<ui5-li accessible-role="menuitem"> List Item</ui5-li>
Now use the enum values instead:
<ui5-li accessible-role="MenuItem"> List Item</ui5-li>
ui5-li-custom
- The web component class has been renamed from
CustomListItemtoListItemCustom.
If you previously imported the class as follows:
import CustomListItem from "@ui5/webcomponents/CustomListItem.js";
Now, change the import to:
import ListItemCustom from "@ui5/webcomponents/ListItemCustom.js";
ui5-list
- The
busyandbusyDelayproperties have been renamed toloadingandloadingDelay.
If you previously used the busy, busyDelay properties:
<ui5-list busy busy-delay="500"></ui5-list>
Now use loading and loadingDelay instead:
<ui5-list loading loading-delay="500"></ui5-list>
- The
modepropertie has been renamed toselectionMode. Additionally th mode values have changed.
If you previously used the mode property and the ListMode values:
<ui5-list mode="SingleSelect">
<ui5-list mode="MultiSelect">
Now use selectionMode and the ListSelectionMode values: Single, Multiple:
<ui5-list selection-mode="Single">
<ui5-list selection-mode="Multiple">
- The enum
ListSeparatorshas been renamed toListSeparator(singular form).
If you previously imported the ListSeparators:
import ListSeparators from "@ui5/webcomponents/dist/types/ListSeparators.js";
import type ListSeparators from "@ui5/webcomponents/dist/types/ListSeparators.js";
Now, import the ListSeparator enumeration as follows:
import ListSeparator from "@ui5/webcomponents/dist/types/ListSeparator.js";
import type ListSeparator from "@ui5/webcomponents/dist/types/ListSeparator.js";
- The grouping of list items is supported with different APIs - the
ui5-li-groupheaderweb component is removed and groups can be formed with theui5-li-group.
Instead of using ui5-li-groupheader as a separator in a flat structure:
<ui5-list>
<ui5-li-groupheader>Actions</ui5-li-groupheader>
<ui5-li>Delete Product</ui5-li>
<ui5-li>Audit Log Settings</ui5-li>
</ui5-list>
Use the ui5-li-group with the header-text property and nest ui5-li web components in the hierarchical structure:
<ui5-list>
<ui5-li-group header-text="Actions">
<ui5-li>Delete Product</ui5-li>
<ui5-li>Audit Log Settings</ui5-li>
</ui5-li-group>
</ui5-list>
- The
accessibleRoleproperty has been updated from a string type to an enum typeListAccessibleRole. The available options for theui5-list: List- Represents the ARIA role "list". (by default)Menu- Represents the ARIA role "menu".Tree- Represents the ARIA role "tree".ListBox- Represents the ARIA role "listbox".
If you previously used:
<ui5-list accessible-role="tree"> List </ui5-list>
Now use the enum values instead:
<ui5-list accessible-role="Tree"> List </ui5-list>
ui5-link
- The
wrappintTypedefault value has been changed fromNonetoNormaland the Link's text will wrap by default.
If you previously set wrapping-type="Normal":
<ui5-link wrapping-type="Normal"></ui5-link>
Now, it's unnecessary and can be removed as the text will wrap by default:
<ui5-link></ui5-link>
If you previously did not use the property at all:
<ui5-link></ui5-link>
Now, you need to set wrapping-type="None" to keep the text truncating:
<ui5-link wrapping-type="None"></ui5-link>
ui5-message-strip
- The property values
Warningare renamed toCritical.
If you previously used it like:
<ui5-message-strip design="Warning"></ui5-message-strip>
Now you have to use it like:
<ui5-message-strip design="Critical"></ui5-message-strip>
ui5-multi-combobox
- The
allowCustomValuesproperty has been renamed tonoValidation.
If you previously used the allowCustomValues property
<ui5-multi-combobox allow-custom-values></ui5-multi-combobox>
Now use noValidation instead:
<ui5-multi-combobox no-validation></ui5-multi-combobox>
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-multi-combobox value-state="Error"></ui5-multi-combobox>
<ui5-multi-combobox value-state="Warning"></ui5-multi-combobox>
<ui5-multi-combobox value-state="Success"></ui5-multi-combobox>
Now you have to use it like:
<ui5-multi-combobox value-state="Negative"></ui5-multi-combobox>
<ui5-multi-combobox value-state="Critical"></ui5-multi-combobox>
<ui5-multi-combobox value-state="Positive"></ui5-multi-combobox>
- The
changeevent used to be fired while navigating between the suggestion items but not anymore since this is not considered a final change. Thechangeevent will be fired after the user confirms the changes in the input field - byfocusout, pressing [Enter] key, or by selecting a suggestion item (by clicking or pressing [Enter] key over an item).
If you previously used change to track live changes within the suggestions:
input.addEventListener("change", (event) => {
});
Now use the selection-change event instead:
input.addEventListener("selection-change", (event) => {
});
ui5-option
- The
disabledproperty of theui5-optionis removed.
If you previously used the disabled property:
<ui5-option disabled>Option</ui5-option>
Now, it won't take effect - rendering disabled options is not recommended from a UX perspective.
<ui5-option>Option</ui5-option>
ui5-popover
- The
LeftandRightoptions have been renamed.
If you previously used them to set the placement or the alignment of the popover:
<ui5-popover horizontal-align="Left" placement-type="Left"></ui5-popover>
Now use Start or End instead:
<ui5-popover horizontal-align="Start" placement-type="Start"></ui5-popover>
- The
placementTypeproperty and thePopoverPlacementTypeenum have been renamed.
If you previously used the placementType property and the PopoverPlacementType
<ui5-popover placement-type="Bottom"></ui5-popover>
import PopoverPlacementType from "@ui5/webcomponents/dist/types/PopoverPlacementType.js";
Now use placement instead:
<ui5-popover placement="Bottom"></ui5-popover>
import PopoverPlacement from "@ui5/webcomponents/dist/types/PopoverPlacement.js";
- Methods
isOpenandcloseare no longer present. Useopenproperty instead.
Previously:
let isOpen = popover.isOpen();
popover.close();
Now:
let isOpen = popover.open;
popover.open = false;
- Method
showAtis no longer present. Useopenandopenerproperties instead.
Previously:
popover.showAt(opener);
Now:
popover.opener = opener;
popover.open = true;
- Parameter
preventInitialFocusfrom methodshowAtis added as a property.
Previously:
popover.showAt(opener, true);
Now:
popover.preventInitalFocus = true;
popover.opener = opener;
popover.open = true;
- Property
hideBackdropis removed.
Previously the application developers could define a modal popover without a visible backdrop as follows:
<ui5-popover modal hide-backdrop>
Now the application developers can use the standard ::backdrop CSS selector
<style>
.transparentBackdrop::backdrop {
background: transparent;
}
</style>
...
<ui5-popover modal class="transparentBackdrop">
- The events
after-closeandafter-openhave been renamed toopenandcloserespectively.
If you previously used the events like:
popover.addEventListener("after-open", (event) => {
});
popover.addEventListener("after-close", (event) => {
});
Now you have to use it like:
popover.addEventListener("open", (event) => {
});
popover.addEventListener("close", (event) => {
});
ui5-progress-indicator
- The
disabledproperty of theui5-progress-indicatoris removed.
If you previously used the disabled property, it won't take effect:
<ui5-progress-indicator disabled value="60"></ui5-progress-indicator>
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-progress-indicator value-state="Error"></ui5-progress-indicator>
<ui5-progress-indicator value-state="Warning"></ui5-progress-indicator>
<ui5-progress-indicator value-state="Success"></ui5-progress-indicator>
Now you have to use it like:
<ui5-progress-indicator value-state="Negative"></ui5-progress-indicator>
<ui5-progress-indicator value-state="Critical"></ui5-progress-indicator>
<ui5-progress-indicator value-state="Positive"></ui5-progress-indicator>
ui5-radio-button
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive. If you previously used it like:
<ui5-radio-button value-state="Error"></ui5-radio-button>
<ui5-radio-button value-state="Warning"></ui5-radio-button>
<ui5-radio-button value-state="Success"></ui5-radio-button>
Now you have to use it like:
<ui5-radio-button value-state="Negative"></ui5-radio-button>
<ui5-radio-button value-state="Critical"></ui5-radio-button>
<ui5-radio-button value-state="Positive"></ui5-radio-button>
- The
wrappintTypedefault value has been changed fromNonetoNormaland the RadioButton text will wrap by default. If you previously setwrapping-type="Normal":
<ui5-radio-button wrapping-type="Normal"></ui5-radio-button>
Now, it's not necessary and can be removed:
<ui5-radio-button></ui5-radio-button>
Now, it's unnecessary and can be removed as the text will wrap by default:
<ui5-radio-button></ui5-radio-button>
Now, you need to set wrapping-type="None" to keep the text truncating:
<ui5-radio-button wrapping-type="None"></ui5-radio-button>
ui5-select
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-select value-state="Error"></ui5-select>
<ui5-select value-state="Warning"></ui5-select>
<ui5-select value-state="Success"></ui5-select>
Now you have to use it like:
<ui5-select value-state="Negative"></ui5-select>
<ui5-select value-state="Critical"></ui5-select>
<ui5-select value-state="Positive"></ui5-select>
ui5-select-menu, ui5-select-menu-option
- The
ui5-select-menuandui5-select-menu-optioncomponents are removed. Custom options can now be created using theui5-option-custom, directly placed inside the default slot of theui5-select.
If you previously used the ui5-select-menu and ui5-select-menu-option:
<ui5-select menu="selectMenu"></ui5-select>
<ui5-select-menu id="selectMenu">
<ui5-select-menu-option>
<div class="optionContent">custom</div>
</ui5-select-menu-option>
</ui5-select-menu>
Now use ui5-select and ui5-option-custom instead:
<ui5-select>
<ui5-option-custom>
<div class="optionContent">custom</div>
</ui5-option-custom>
</ui5-select>
ui5-segmented-button
- The property
modehas been renamed toselectionMode. The selection modes are renamed fromSingleSelectandMultiSelecttoSingleandMultiple.
If you previously used it as follows:
<ui5-segmented-button mode="SingleSelect"></ui5-segmented-button>
<ui5-segmented-button mode="MultiSelect"></ui5-segmented-button>
Now you have to use:
<ui5-segmented-button selection-mode="Single"></ui5-segmented-button>
<ui5-segmented-button selection-mode="Multiple"><ui5-segmented-button>
- The
pressedproperty has been renamedselected.
If you previously used pressed:
<ui5-segmented-button>
<ui5-segmented-button-item pressed> Option 1</ui5-segmented-button-item>
<ui5-segmented-button-item>Option 2</ui5-segmented-button-item>
<ui5-segmented-button-item>Option 3</ui5-segmented-button-item>
</ui5-segmented-button>
Now use selected instead:
<ui5-segmented-button>
<ui5-segmented-button-item selected> Option 1</ui5-segmented-button-item>
<ui5-segmented-button-item>Option 2</ui5-segmented-button-item>
<ui5-segmented-button-item>Option 3</ui5-segmented-button-item>
</ui5-segmented-button>
- The read-only getter
selectedItemhas been replaced byselectedItemsas multiple items can be selected.
ui5-segmented-button-item
- The property
pressedhas been renamed toselected.
If you previously used it as follows:
<ui5-segmented-button id="segButton1">
<ui5-segmented-button-item>Item 1</ui5-segmented-button-item>
<ui5-segmented-button-item pressed>Item 2</ui5-segmented-button-item>
</ui5-segmented-button>
Now you have to use it as follows:
<ui5-segmented-button id="segButton1">
<ui5-segmented-button-item>Item 1</ui5-segmented-button-item>
<ui5-segmented-button-item selected>Item 2</ui5-segmented-button-item>
</ui5-segmented-button>
- The property
designhas been inherited but never had effect and it's now removed. - The property
iconEndhas been inherited but never had effect and it's now removed. - The property
submitshas been inherited but never had effect and it's now removed. - The property
typehas been inherited but never had effect and it's now removed. - The property
accessibilityAttributeshas been inherited but never had effect and it's now removed. - The property
accessibleRolehas been inherited but never had effect and it's now removed.
ui5-step-input
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive. If you previously used it like:
<ui5-step-input value-state="Error"></ui5-step-input>
<ui5-step-input value-state="Warning"></ui5-step-input>
<ui5-step-input value-state="Success"></ui5-step-input>
Now you have to use it like:
<ui5-step-input value-state="Negative"></ui5-step-input>
<ui5-step-input value-state="Critical"></ui5-step-input>
<ui5-step-input value-state="Positive"></ui5-step-input>
ui5-split-button
- The
activeIconproperty is no longer present as dropped by specs. The active icon used to be displayed while the SplitButton is pressed. This is a behavior that is not recommended from a UX point of view.
If you previosuly used activeIcon:
<ui5-split-button icon="employee" active-icon="accept">Text</ui5-split-button>
Now, the property is not available and must not be set:
<ui5-split-button icon="employee">Text</ui5-split-button>
ui5-table
- The Table, TableCell, TableRow, and TableColumn that used to be part of the
@ui5/webcomponentshave been moved to a new package@ui5/webcomponents-compat. The classes are moved, but the tag names and the APIs remain the same.
If you previously used the Table from @ui5/webcomponents:
import "@ui5/webcomponents/dist/Table.js"; // ui5-table
import "@ui5/webcomponents/dist/TableColumn.js"; // ui5-table-column
import "@ui5/webcomponents/dist/TableRow.js"; // ui5-table-row`
import "@ui5/webcomponents/dist/TableGroupRow.js";` // ui5-table-group-row
import "@ui5/webcomponents/dist/TableCell.js"; // ui5-table-cell
Now, import the web components from @ui5/webcomponents-compat instead:
import "@ui5/webcomponents-compat/dist/Table.js"; // ui5-table
import "@ui5/webcomponents-compat/dist/TableColumn.js"; // ui5-table-column
import "@ui5/webcomponents-compat/dist/TableRow.js"; // ui5-table-row`
import "@ui5/webcomponents-compat/dist/TableGroupRow.js";` // ui5-table-group-row
import "@ui5/webcomponents-compat/dist/TableCell.js"; // ui5-table-cell
Or, switch to the new v2 Table - the successor or the v1 Table:
There is a brand new Table implementation in the @ui5/webcomponents package available since version 2.0 that will be the successor of the Table from version 1.0. However, for a short period the newly introduced v2 Table will be experimental (its API is subject to change) and until we productize it, we will maintain the v1 Table inside the @ui5/webcomponents-compat package.
After removing the experimental flag of the v2 Table, we will deprecate and remove the v1 Table.
ui5-time-picker
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-time-picker value-state="Error"></ui5-time-picker>
<ui5-time-picker value-state="Warning"></ui5-time-picker>
<ui5-time-picker value-state="Success"></ui5-time-picker>
Now you have to use it like:
<ui5-time-picker value-state="Negative"></ui5-time-picker>
<ui5-time-picker value-state="Critical"></ui5-time-picker>
<ui5-time-picker value-state="Positive"></ui5-time-picker>
- The methods
openPicker(),closePicker(), andisOpen()have been removed in favor of theopenproperty.
If you previously used openPicker() and closePicker() to toggle the TimePicker:
timePicker.openPicker();
timePicker.closePicker();
Now, you must use the open property to toggle the TimePicker:
timePicker.open = true;
timePicker.open = false;
ui5-tab-container
-
The property
fixedhas been removed and there is no alternative provided. The TabContainer is no longer expandable/collapsible via use interaction. You can still show the TabContainer in collapsed mode via thecollapsedproperty. -
The property
tabsOverflowModehas been renamed tooverflowMode.
If you previously used:
<ui5-tabcontainer tabs-overflow-mode="StartAndEnd"></ui5-tabcontainer>
Now use:
<ui5-tabcontainer overflow-mode="StartAndEnd"></ui5-tabcontainer>
-
If you previously imported
TabContainerBackgroundDesign, useBackgroundDesigninstead. -
The
showOverflowproperty has been removed removed.
If previously you have used:
<ui5-tabcontainer show-overflow></ui5-tabcontainer>
Now use the overflowButton slot instead:
<ui5-tabcontainer>
<ui5-button slot="startOverflowButton" id="startOverflowButton">Start</ui5-button>
<ui5-button slot="overflowButton" id="endOverflowButton">End</ui5-button>
</ui5-tabcontainer>
- You can no longer import and implement the
ITabinterface. TabContainer is designed to work only with Tab and TabSeparator classes and the interface has been obsolete.
ui5-tab
- The
getTabInStripDomRefmethod has been renamed togetDomRefInStrip.
If previously you have used:
someTab.getTabInStripDomRef();
Now use:
someTab.getDomRefInStrip();
- The
subTabsslot has been renamed toitems.
If you previously used:
<ui5-tab id="nestedTab" slot="subTabs"></ui5-tab>
Now use the slot name:
<ui5-tab id="nestedTab" slot="items"></ui5-tab>
ui5-tab-separator
- The getTabInStripDomRef
method has been renamed togetDomRefInStrip`.
If previously used:
someTabSeparator.getTabInStripDomRef();
Now use:
someTabSeparator.getDomRefInStrip();
ui5-textarea
- The
growingMaxLinesproperty has been renamed togrowingMaxRows.
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-textarea value-state="Error"></ui5-textarea>
<ui5-textarea value-state="Warning"></ui5-textarea>
<ui5-textarea value-state="Success"></ui5-textarea>
Now you have to use it like:
<ui5-textarea value-state="Negative"></ui5-textarea>
<ui5-textarea value-state="Critical"></ui5-textarea>
<ui5-textarea value-state="Positive"></ui5-textarea>
ui5-title
- The default value of the
wrappingTypeproperty has been changed fromNonetoNormal.
Previously long texts would truncate if there is not enough space:
<ui5-title>some very very very long title</ui5-title> <!-- text will truncate if there is not enough space -->
Now, long texts would wrap:
<ui5-title>some very very very long title</ui5-title> <!-- text will wrap if there is not enough space -->
And you need to set wrapping-type="None" explicitly to make it truncate as before:
<ui5-title wrapping-type="None">some very very very long title</ui5-title> <!-- will truncate the text -->
ui5-tree
- The property
modehas been renamed toselectionMode. Also, the mode values have changed.
If you previously used the mode property and the ListMode values:
<ui5-tree mode="SingleSelect">
<ui5-tree mode="MultiSelect">
Now use selectionMode and Single, Multiple, and the ListSelectionMode values instead:
<ui5-tree selection-mode="Single">
<ui5-tree selection-mode="Multiple">
ui5-tree-item
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-tree-item highlight="Error"></ui5-tree-item>
<ui5-tree-item highlight="Warning"></ui5-tree-item>
<ui5-tree-item highlight="Success"></ui5-tree-item>
Now you have to use it like:
<ui5-tree-item highlight="Negative"></ui5-tree-item>
<ui5-tree-item highlight="Critical"></ui5-tree-item>
<ui5-tree-item highlight="Success"></ui5-tree-item>
- The
valueStateproperty valuesError/Warning/Successare renamed toNegative/Critical/Positive.
If you previously used it like:
<ui5-tree-item additional-text-state="Error"></ui5-tree-item>
<ui5-tree-item additional-text-state="Warning"></ui5-tree-item>
<ui5-tree-item additional-text-state="Success"></ui5-tree-item>
Now you have to use it like:
<ui5-tree-item additional-text-state="Negative"></ui5-tree-item>
<ui5-tree-item additional-text-state="Critical"></ui5-tree-item>
<ui5-tree-item additional-text-state="Positive"></ui5-tree-item>
ui5-toast
- The
after-closeevent has been renamed toclose.
If you previously used it like:
toast.addEventListener("after-close", (event) => {
});
Now you have to use it like:
toast.addEventListener("close", (event) => {
});
- The
showmethod has been replaced byopenproperty.
If you previously used the show() method:
toast.show();
Now, you must use the open property:
toast.open=true;
ui5-toolbar-button
- The boolean property
iconEndthat is used to define the placement of the icon (to the start or to the end) has been replaced by string propertyendIcon, defining the icon, displayed at the end.
If you previously set icon and icon-end to display an icon after the ToolbarButton's text:
<ui5-toolbar-button icon="home" icon-end>Button</ui5-toolbar-button>
Now, you must use the new property:
<ui5-toolbar-button end-icon="home">Button</ui5-toolbar-button>
Furhtermore, this allows the displaying of two icons - to the start and to the end:
<ui5-toolbar-button icon="employee" end-icon="home">Button</ui5-toolbar-button>
@ui5/webcomponents-fiori
ui5-bar
- The
ui5-barcomponent is now inmainlibrary.
If you previously imported the ui5-bar from fiori:
import "@ui5/webcomponents-fiori/dist/Bar.js;
Now, import the ui5-bar from main:
import "@ui5/webcomponents/dist/Bar.js";
ui5-barcode-scanner-dialog
- The
showandclosepublic methods have been removed. Use the public propertyopeninstead.
If you previously used
bsd.show();
bsd.close();
Now use the open property instead:
bsd.open = true;
...
bsd.open = false;
ui5-flexible-column-layout
- The
accessibilityTextsandaccessibilityRolesproperties of theui5-flexible-column-layouthave been removed.
If you previously used the accessibilityTexts or accessibilityRoles properties:
fcl.accessibilityTexts = {
startColumnAccessibleName: "Products list",
midColumnAccessibleName: "Product information",
endColumnAccessibleName: "Product detailed information",
startArrowLeftText: "Collapse products list",
startArrowRightText: "Expand products list",
endArrowLeftText: "Expand product detailed information",
endArrowRightText: "Collapse product detailed information",
startArrowContainerAccessibleName: "Start Arrow Container",
endArrowContainerAccessibleName: "End Arrow Container",
}
fclAccRoles.accessibilityRoles = {
startColumnRole: "complementary",
startArrowContainerRole: "navigation",
midColumnRole: "main",
endArrowContainerRole: "navigation",
endColumnRole: "complementary".
}
Now use accessibilityAttributes instead:
fcl.accessibilityAttributes = {
startColumn: {
role: "complementary"
name: "Products list",
},
midColumn: {
role: "complementary"
name: "Product information",
},
endColumn: {
role: "complementary"
name: "Product detailed information",
},
startSeparator: {
role: "navigation",
name: "Start Separator",
},
endSeparator: {
role: "navigation",
name: "End Separator",
},
};
- The
arrowUsedandarrowsUseddetails of thelayoutChangeevent have been replaced by theseparatorsUseddetail.
If you previously used:
fcl.addEventListener("layout-change", function(e) {
const isUserInteraction = e.detail.arrowsUsed;
}
Now use the new parameter instead:
fcl.addEventListener("layout-change", function(e) {
const isUserInteraction = e.detail.separatorsUsed;
}
- The
resizeparameter of thelayoutChangeevent has been renamed toresized.
If you previously used:
fcl.addEventListener("layout-change", function(e) {
const isGlobalResize = e.detail.resize;
}
Now use the new name:
fcl.addEventListener("layout-change", function(e) {
const isGlobalResize = e.detail.resized;
}
- The property
hideArrowshas been renamed todisableResizing.
If you previously used hideArrows:
<ui5-flexible-column-layout hide-arrows/>
Now use disableResizing instead:
<ui5-flexible-column-layout disable-resizing/>
ui5-illustrated-message
- The
sizeproperty of theui5-illustrated-messageis renamed todesign.
If you previously used the size property:
<ui5-illustrated-message size="Dialog">
Now use design instead:
<ui5-illustrated-message design="Dialog">
- The
titleLevelproperty has been removed and replaced bytitleslot allowing user-defined titles with the desired title level.
If you previously used the titleLevel property:
<ui5-illustrated-message title-level="H6></ui5-illustrated-message>
Now use the title slot and define your title and title level:
<ui5-illustrated-message>
<ui5-title slot="title" level="H3">This is a slotted title</ui5-title>
</ui5-illustrated-message>
ui5-shellbar
- The
accessibilityTextsandaccessibilityRolesproperties of theui5-shellbarare removed.
If you previously used the accessibilityTexts or accessibilityRoles properties:
shellbar.accessibilityTexts = {
profileButtonTitle: "John Dow",
logoTitle: "Custom logo title",
}
shellbar.accessibilityRoles = {
logoRole: "link"
};
Now use accessibilityAttributes instead:
shellbar.accessibilityAttributes = {
profile: {
name: "John Dow",
},
logo: {
role: "link"
name: "Custom logo title"
},
};
ui5-side-navigation-item
- The
wholeItemToggleableproperty is now removed. The functionality of clicking the whole item to show/hide the sub-items is no longer available. - The collapsing/expanding of the item can still be done by pressing the icon.
ui5-notification-list
- Although the
ui5-liststill exists, the newui5-notification-listweb component should be used as a container forui5-li-notificationandui5-li-notification-groupweb components.
If you previously used notifications inside ui5-list:
<ui5-list>
<ui5-li-notification>
...
Now, for better accessibility, use the ui5-notification-list instead:
<ui5-notification-list>
<ui5-li-notification>
...
ui5-li-notification
- The
priorityproperty of theui5-li-notificationis replaced by the new propertystate.
If you previously used the priority property:
<ui5-li-notification priority="Medium">
Now use state instead:
<ui5-li-notification state="Critical">
- The
busy,busyDelayproperties have been renamed toloadingandloadingDelay.
If you previously used the busy, busyDelay properties:
<ui5-li-notification busy busy-delay="500"></ui5-li-notification>
Now you must use loading and loadingDelay properties:
<ui5-li-notification loading loading-delay="500"></ui5-li-notification>
- The
actionsslot of theui5-li-notificationis replaced by the new slotmenu.
If you previously used the actions slot:
<ui5-li-notification>
<ui5-notification-action slot="actions" icon="message-error" text="Reject">
</ui5-notification-action>
Now use menu instead:
<ui5-li-notification>
<ui5-menu slot="menu">
<ui5-menu-item icon="message-error" text="Reject"></ui5-menu-item>
</ui5-menu>
ui5-li-notification-group
-
The properties "showClose", "showCounter", "priority", the event "close" and the slot "actions" are removed and there are no alternatives provided. The NotificationGroup no longer shows a "Close" button, counter text, priority, and actions.
-
The
busyandbusyDelayproperties have been renamed toloadingandloadingDelayproperties.
If you previously used the busy, busyDelay properties:
<ui5-li-notification-group busy busy-delay="500"></ui5-li-notification-group>
Now, use loading and loadingDelay instead:
<ui5-li-notification-group loading loading-delay="500"></ui5-li-notification-group>
ui5-page
| Changed item | Old | New
| Property | disableScrolling | noScrolling |
| Property | floatingFooter | fixedFooter |
- The
disableScrollingproperty has been renamed tonoScrolling.
If you previously used the disableScrolling property:
<ui5-page disable-scrolling> </ui5-page>
Now use noScrolling instead:
<ui5-page no-scrolling> </ui5-page>
- The
floatingFooterproperty has been replaced byfixedFooterto change the default behavior. By default, the footer will float
If you previously used the floatingFooter property to have a floating footer:
<ui5-page floating-footer>
<ui5-bar slot="footer" design="FloatingFooter"></ui5-bar>
</ui5-page>
Now, that is the default behavior:
<ui5-page>
<ui5-bar slot="footer" design="Footer"></ui5-bar>
</ui5-page>
Furthermore, to get a fixed footer that is always placed at the very bottom of the page, use fixedFooter instead:
<ui5-page fixed-footer>
<ui5-bar slot="footer" design="Footer"></ui5-bar>
</ui5-page>
ui5-upload-collection
- The
modeproperty has been renamed toselectionMode. Also, the mode values have changed.
If you previously used the mode property and the SingleSelect, MultiSelect values:
<ui5-upload-collection mode="SingleSelect">
<ui5-upload-collection mode="MultiSelect">
Now use the selectionMode property and Single, Multiple values instead:
<ui5-upload-collection selection-mode="Single">
<ui5-upload-collection selection-mode="Multiple">
- The
selectionModeproperty no longer accepts "Delete" as a value.
If you previously used it:
<ui5-upload-collection selection-mode="Delete"></ui5-upload-collection>
Now omit it completely and use hide-delete-button on the ui5-upload-collection:
<ui5-upload-collection>
<ui5-upload-collection-item hide-delete-button> </ui5-upload-collection-item>
</ui5-upload-collection>
- Removed the
IUploadCollectionIteminterface.
If you previously used the interface:
import type { IUploadCollectionItem} from "@ui5/webcomponents-fiori/dist/UploadCollection.js"
Now use the UploadCollectionItem type instead:
import type UploadCollectionItem from "@ui5/webcomponents-fiori/dist/UploadCollectionItem.js"
ui5-view-settings-dialog
- The
showandclosepublic methods have been removed. Use the public propertyopeninstead.
If you previously used:
vsd.show();
...
vsd.close();
Now use the open property instead:
vsd.open = true;
...
vsd.open = false;
ui5-wizard
- The
changeWithClickevent detail has been renamed towithScroll.
If you previously listened for the step-change event and used the changeWithClick:
wizard.addEventListener("step-change", () => {
const stepChangedWithClick = e.detail.changeWithClick;
})
Now you have to use the new event name and details:
wizard.addEventListener("step-change", () => {
const stepChangedWithScroll = e.detail.withScroll;
})
@ui5/webcomponents-icons
- Removed
soccoricon. Usesoccerinstead. - Removed
add-polygoneicon. Useadd-polygoninstead. - Icons now export
getPathDataasync method, instead of thepathDatastring.
If you imported the pathData, for example:
import { pathData } from "@ui5/webcomponents-icons/dist/accept.js";
console.log(pathData); // String containing the SVG path
Now, you must change your code to, for example:
import { getPathData } from "@ui5/webcomponents-icons/dist/accept.js";
getPathData().then(pathData => {
console.log(pathData); // String containing the SVG path
});
@ui5/create-webcomponents-package
- The JavaScript template option has been removed.
If you previously ran npm init @ui5/webcomponents-package to create a JS-based project
the command will create a TypeScript-based project.
- The TypEscript option
--enable-typescripthas been removed.
If you previously used npm init @ui5/webcomponents-package --enable-typescript to create a TypeScript-based project, now it's by default
Other
- The JSDoc plugin has been removed, and the generation of
api.jsonhas stopped.
If you previously relied on the {package}/dist/api.json file, now use the {package}/dist/custom-elements.json.
- All
Assets-static.jsmodules have been removed.
If you previously imported any Assets-static.js module from any package:
import "@ui5/webcomponents/dist/Assets-static.js";
import "@ui5/webcomponents-icons/dist/Assets-static.js"
import "@ui5/webcomponents-icons-tnt/dist/Assets-static.js"
import "@ui5/webcomponents-icons-business-suite/dist/Assets-static.js"
import "@ui5/webcomponents-localization/dist/Assets-static.js"
import "@ui5/webcomponents-theming/dist/Assets-static.js"
Now use the dynamic equivalent of it:
import "@ui5/webcomponents/dist/Assets.js";
import "@ui5/webcomponents-icons/dist/Assets.js";
import "@ui5/webcomponents-icons-tnt/dist/Assets.js";
import "@ui5/webcomponents-icons-business-suite/dist/Assets.js";
import "@ui5/webcomponents-localization/dist/Assets.js";
import "@ui5/webcomponents-theming/dist/Assets.js"