Skip to main content

Properties

In this article, we will discuss properties in the context of UI5 Web Components.

Properties and Attributes​

Properties allow you to configure the state of your component.

By default, for each property, there is an equivalent attribute. Attributes have the same names as properties but in kebab-case rather than camelCase. Properties of type Object or Array and properties with noAttribute set to true do not have an attribute equivalent.

@property decorator​

To define your own property, you need to:

  • Use the property decorator.
  • Define a class member.

The property decorator is a property decorator that takes one optional argument as an object literal containing configuration options for the property.

Note: If no argument is provided to the decorator, the property will be treated as having a String type.

import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import property from "@ui5/webcomponents-base/dist/decorators/property.js";

@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
@property({ type: Boolean })
myProp = false;
}

You can see the available options below.

type​

This option is required and accepts a type constructor (e.g., Boolean, String) that will be used for attribute conversion. When converting from a property to an attribute, the framework can check the runtime type and convert it to a string, but when coming from an attribute, there is no way to know whether it is a boolean or a number, unless a type is provided.

import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import property from "@ui5/webcomponents-base/dist/decorators/property.js";

@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
@property({ type: Number })
myProp = 0;
}

Available types:

TypeClass to UseDescription
stringStringThis is the default type, does not need to be explicitly set
booleanBooleanBoolean value, the presence of the attribute will set the property to true
numberNumberNumber value, the attribute will be converted using parseFloat
objectObjectJS Object, automatically applies noAttribute: true
arrayArrayJS Array, automatically applies noAttribute: true
enumerationStringEnums are treated as strings, type does not accept enum types

noAttribute​

This option accepts a boolean value and defines whether the property should not have an equivalent attribute (f.e. for properties that do not used for CSS selectors).

import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import property from "@ui5/webcomponents-base/dist/decorators/property.js";

@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
@property({ type: Number, noAttribute: true })
myProp = 0;
}

converter​

This option accepts an object and allows you to define a custom property-to-attribute (and vice-versa) converter with two methods - fromAttribute and toAttribute that will receive the type and the value.

import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import property from "@ui5/webcomponents-base/dist/decorators/property.js";

@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
@property({
converter: {
toAttribute(propertyValue: string | HTMLElement) {
if (propertyValue instanceof HTMLElement) {
return null;
}
return propertyValue;
},
fromAttribute(value: string | null) {
return value;
}
}
})
myProp?: HTMLElement | string;
}

Default Value​

Use JavaScript property initializers to define default values.

import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
import property from "@ui5/webcomponents-base/dist/decorators/property.js";

@customElement("my-demo-component")
class MyDemoComponent extends UI5Element {
@property()
name = "user1";

@property({ type: Boolean })
collapsed = false;

@property({ type: Number })
maxValue = 5;

@property({ type: Object })
accProperties = {};

@property({ type: Array })
stars = [];
}

Note: due to how HTML attributes work, boolean properties can only have false as a default value.