Rating — Smart UI JavaScript API

Rating — Smart UI JavaScript API

On this page + Quick start

Quick start · JavaScript

Complete starter source per framework. Run the scaffold/install command first, then replace the listed files with the full code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Rating - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-rating id="demo-rating"></smart-rating>

  <script type="module">
    import './node_modules/smart-webcomponents/source/modules/smart.rating.js';

    const el = document.getElementById('demo-rating');
    if (el) {

      el.max = 5;
      el.value = 4;

      el.addEventListener('change', (event) => console.log('change:', event.detail || event));
    }
  </script>
</body>
</html>
For AI tooling

Developer Quick Reference

Component: Rating   Framework: JavaScript   Selector: smart-rating

API counts: 12 properties, 2 methods, 1 events

Common properties: 0, 1, 2, 3, 4, 5

Common methods: getValue(), setValue()

Common events: change

Module hint: smart-webcomponents/source/modules/smart.rating.js

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

Class

Rating

Rating

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

Selector

smart-rating

Quick picks

changedisabledvalue

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.
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.
UunlockKeyGets or sets the unlockKey property, which serves as the credential required to unlock and activate the product’s full functionality.
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

animationGets 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."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"

Examples

Markup and runtime examples for animation:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

disabledPrevents 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.boolean

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

Examples

Markup and runtime examples for disabled:

HTML attribute:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

localeSpecifies 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.string

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"

Examples

Markup and runtime examples for locale:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

localizeFormatFunctionA 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.function | 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.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

maxSpecifies 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.number

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.

Examples

Markup and runtime examples for max:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

messagesSpecifies 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.object

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."

}

Examples

Markup and runtime examples for messages:

HTML:

<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>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-rating');
el.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."}};

Read the current value:

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

nameSpecifies 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.string

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

""

Examples

Markup and runtime examples for name:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

rightToLeftSets 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.boolean

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.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

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

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

Default value

""

Examples

Markup and runtime examples for theme:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

unfocusableWhen 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.boolean

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

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

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

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

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

valueSpecifies 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.number

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.

Examples

Markup and runtime examples for value:

HTML:

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

Vanilla JS — prefer #id if multiple widgets exist on the page:

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

Read the current value:

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

Events

changeThis 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.CustomEvent

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.

Examples

Listen for change using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

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

	// event handling code goes here.
})

Methods

getValue(): numberRetrieve the current value assigned to the rating property, indicating the user's selected rating or the rating score for the item.

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

Returnsnumber

On the custom element in the DOM (narrow the selector, e.g. to #my-rating, if you host multiple widgets):

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

setValue( value: number): voidAssigns 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.

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

On the custom element in the DOM (narrow the selector, e.g. to #my-rating, if you host multiple widgets):

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