Rating JAVASCRIPT UI Component API

Rating Javascript API

Class

Rating

Rating

Rating allows you to input a rating. It is broadly used in applications with reviews.

Selector

smart-rating

Properties

AanimationGets or sets the animation mode for the component. When this property is set to 'none', all animations are disabled, and transitions will occur instantly without any animated effects. Use this property to enable, disable, or modify the animation behavior as needed.
DdisabledPrevents any user interaction with the element, making it unresponsive to mouse, keyboard, and touch events such as clicks, focus, or input. The element will appear visually inactive and will not trigger any associated event handlers.
UunlockKeyGets or sets the unlockKey property, which serves as the credential required to unlock and activate the product’s full functionality.
LlocaleSpecifies or retrieves the current language setting. This property determines which localized set of messages (defined in the messages property) will be used for display and communication. Use this property to dynamically change the language of the interface by updating it in conjunction with the messages object.
LlocalizeFormatFunctionA function that allows you to customize how messages are formatted before they are returned by the Localization Module. This callback receives the original message and any associated variables, enabling you to adjust the output format, apply additional logic, or support advanced localization requirements.
MmaxSpecifies the total number of stars to display in the rating component. This value controls how many individual star icons are shown, allowing users to select a rating between 1 and the specified number.
MmessagesSpecifies or retrieves an object containing the localized strings used by the element. This property allows you to define text labels, messages, or other UI strings that can be translated based on the user's language or region. It is typically used together with the locale property to display the appropriate translations for different locales.
NnameSpecifies the name attribute of the element, which is used as the key when the form data is submitted. This allows the value of the element to be identified and processed on the server side.
RrightToLeftSets or retrieves a value that specifies whether the element's text direction and alignment are configured for right-to-left (RTL) languages, such as Arabic or Hebrew. Enabling this option ensures that the element properly supports locales that use RTL scripts.
TthemeSpecifies the theme to be applied. The selected theme controls the visual appearance, including colors, fonts, and styling, of the element.
UunfocusableWhen set to true, this property prevents the element from receiving keyboard focus, making it impossible for users to navigate to the element using the Tab key or similar methods.
VvalueSpecifies how many stars should be visually highlighted to indicate the current rating value. This number determines which stars appear filled or active in the rating component.

Events

CchangeThis event is triggered whenever the user adjusts the slider to a new value, either by dragging the handle or using keyboard controls. It fires each time the slider's value is updated, allowing you to respond dynamically to user input and capture the current value in real time.

Methods

GgetValueRetrieve the current value assigned to the rating property, indicating the user's selected rating or the rating score for the item.
SsetValueAssigns or updates the current rating value. This property determines the selected rating level, typically represented by a numeric value (e.g., 1 to 5), and can be used to display the user’s chosen rating or set a default rating programmatically.

Properties

animation"none" | "simple" | "advanced"

Gets or sets the animation mode for the component. When this property is set to 'none', all animations are disabled, and transitions will occur instantly without any animated effects. Use this property to enable, disable, or modify the animation behavior as needed.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Example

Set the animation property. 

 <smart-rating animation='none'></smart-rating>

Set the animation property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.animation = 'simple';

Get the animation property. 

 const rating = document.querySelector('smart-rating');
 let animation = rating.animation;

disabledboolean

Prevents any user interaction with the element, making it unresponsive to mouse, keyboard, and touch events such as clicks, focus, or input. The element will appear visually inactive and will not trigger any associated event handlers.

Default value

false

Example

Set the disabled property. 

 <smart-rating disabled></smart-rating>

Set the disabled property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.disabled = false;

Get the disabled property. 

 const rating = document.querySelector('smart-rating');
 let disabled = rating.disabled;

unlockKeystring

Gets or sets the unlockKey property, which serves as the credential required to unlock and activate the product’s full functionality.

Default value

""

Example

Set the unlockKey property. 

 <smart-rating unlock-key=''></smart-rating>

Set the unlockKey property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property. 

 const rating = document.querySelector('smart-rating');
 let unlockKey = rating.unlockKey;

localestring

Specifies or retrieves the current language setting. This property determines which localized set of messages (defined in the messages property) will be used for display and communication. Use this property to dynamically change the language of the interface by updating it in conjunction with the messages object.

Default value

"en"

Example

Set the locale property. 

 <smart-rating locale='de'></smart-rating>

Set the locale property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.locale = 'fr';

Get the locale property. 

 const rating = document.querySelector('smart-rating');
 let locale = rating.locale;

localizeFormatFunctionfunction | null

A function that allows you to customize how messages are formatted before they are returned by the Localization Module. This callback receives the original message and any associated variables, enabling you to adjust the output format, apply additional logic, or support advanced localization requirements.

Example

Set the localizeFormatFunction property. 

 <smart-rating localize-format-function='function(defaultMessage, message, messageArguments){return '...'}'></smart-rating>

Set the localizeFormatFunction property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property. 

 const rating = document.querySelector('smart-rating');
 let localizeFormatFunction = rating.localizeFormatFunction;

maxnumber

Specifies the total number of stars to display in the rating component. This value controls how many individual star icons are shown, allowing users to select a rating between 1 and the specified number.

Default value

Try a demo showcasing the max property.

Example

Set the max property. 

 <smart-rating max='5'></smart-rating>

Set the max property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.max = 10;

Get the max property. 

 const rating = document.querySelector('smart-rating');
 let max = rating.max;

messagesobject

Specifies or retrieves an object containing the localized strings used by the element. This property allows you to define text labels, messages, or other UI strings that can be translated based on the user's language or region. It is typically used together with the locale property to display the appropriate translations for different locales.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Example

Set the messages property. 

 <smart-rating messages='{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss."}}'></smart-rating>

Set the messages property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Get the messages property. 

 const rating = document.querySelector('smart-rating');
 let messages = rating.messages;

namestring

Specifies the name attribute of the element, which is used as the key when the form data is submitted. This allows the value of the element to be identified and processed on the server side.

Default value

""

Example

Set the name property. 

 <smart-rating name='rating1'></smart-rating>

Set the name property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.name = 'rating2';

Get the name property. 

 const rating = document.querySelector('smart-rating');
 let name = rating.name;

rightToLeftboolean

Sets or retrieves a value that specifies whether the element's text direction and alignment are configured for right-to-left (RTL) languages, such as Arabic or Hebrew. Enabling this option ensures that the element properly supports locales that use RTL scripts.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-rating right-to-left></smart-rating>

Set the rightToLeft property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.rightToLeft = true;

Get the rightToLeft property. 

 const rating = document.querySelector('smart-rating');
 let rightToLeft = rating.rightToLeft;

themestring

Specifies the theme to be applied. The selected theme controls the visual appearance, including colors, fonts, and styling, of the element.

Default value

""

Example

Set the theme property. 

 <smart-rating theme='blue'></smart-rating>

Set the theme property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.theme = 'red';

Get the theme property. 

 const rating = document.querySelector('smart-rating');
 let theme = rating.theme;

unfocusableboolean

When set to true, this property prevents the element from receiving keyboard focus, making it impossible for users to navigate to the element using the Tab key or similar methods.

Default value

false

Example

Set the unfocusable property. 

 <smart-rating unfocusable></smart-rating>

Set the unfocusable property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.unfocusable = false;

Get the unfocusable property. 

 const rating = document.querySelector('smart-rating');
 let unfocusable = rating.unfocusable;

valuenumber

Specifies how many stars should be visually highlighted to indicate the current rating value. This number determines which stars appear filled or active in the rating component.

Default value

Try a demo showcasing the value property.

Example

Set the value property. 

 <smart-rating value='5'></smart-rating>

Set the value property by using the HTML Element's instance. 

 const rating = document.querySelector('smart-rating');
 rating.value = 1;

Get the value property. 

 const rating = document.querySelector('smart-rating');
 let value = rating.value;

Events

changeCustomEvent

This event is triggered whenever the user adjusts the slider to a new value, either by dragging the handle or using keyboard controls. It fires each time the slider's value is updated, allowing you to respond dynamically to user input and capture the current value in real time.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onChange

Arguments

evCustomEvent
ev.detailObject
ev.detail.value - A numeric value indicating the scroll position.
ev.detail.oldValue - A numeric value indicating the previous scroll position.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of change event. 

const rating = document.querySelector('smart-rating');
rating.addEventListener('change', function (event) {
    const detail = event.detail,
        value = detail.value,
        oldValue = detail.oldValue;

	// event handling code goes here.
})

Methods

getValue(): number

Retrieve the current value assigned to the rating property, indicating the user's selected rating or the rating score for the item.

Returnsnumber

Invoke the getValue method.

const rating = document.querySelector('smart-rating');
const result = rating.getValue();

setValue( value: number): void

Assigns or updates the current rating value. This property determines the selected rating level, typically represented by a numeric value (e.g., 1 to 5), and can be used to display the user’s chosen rating or set a default rating programmatically.

Arguments

valuenumber

Sets the value of the rating


Invoke the setValue method.

const rating = document.querySelector('smart-rating');
rating.setValue(10);