Ratings

The ratings component allows users to provide or display a rating using a row of stars. It is commonly used for evaluating products, services, or content.

The component supports both interactive ratings, where users can select a value, and read-only ratings, where the rating is only displayed.

Examples

Basic Ratings

The first example demonstrates a basic interactive ratings component with the default configuration. The stars are interactive, allowing users to choose a rating directly within the component.

import "spatial-design-system/primitives/ar-ratings.js";

<a-ar-ratings 
    position="0 1.6 -1"
    color="#ECECEC"
></a-ar-ratings>

Readonly Ratings

The second example demonstrates a read-only ratings component. The rating is displayed but cannot be changed by the user. This is useful for showing previously submitted ratings or aggregated scores. Custom colors are also applied to highlight the selected stars.

import "spatial-design-system/primitives/ar-ratings.js";

<a-ar-ratings 
    position="0 1.6 -1" 
    activecolor="#FFD700" 
    color="#CCCCCC"
    readonly="true"
></a-ar-ratings>

Custom Size & Length

This example demonstrates customization of the ratings component, including adjusting the number of rating items, modifying the star size, and setting an initial rating value. The clearable option is disabled, so clicking the currently selected rating will not reset the value, unlike the previous examples.

import "spatial-design-system/primitives/ar-ratings.js";

<a-ar-ratings 
    position="0 1.6 -1" 
    activecolor="#FFD700" 
    color="#CCCCCC"
    clearable="false"
    size="small"
    length="10"
    value="7"
></a-ar-ratings>

Props

Property	Type	Default	Description
visible	boolean	true	Determines whether the ratings component is visible in the scene.
position	number[]	0 0 0	Defines the 3D position of the ratings component in the format [x, y, z].
opacity	number	1	Controls the transparency of the ratings component (0 = fully transparent, 1 = fully visible).
color	string	1	Defines the color of inactive (unselected) stars.
activecolor	string	1	Defines the color of active (selected) stars.
size	enum (small, medium, large)	medium	Specifies the size of the rating stars.
length	number	5	Specifies the total number of stars displayed in the ratings component.
value	number	3	Specifies the currently selected rating value.
readonly	boolean	false	If enabled, the rating cannot be changed by the user and is displayed for informational purposes only.
clearable	boolean	false	Allows the user to clear the selected rating by clicking the currently selected value again.

Events

The ratings component emits the following event when interacted with:

Event	Parameters	Description
rating-changed	{ value: number }	Emitted whenever the selected rating changes. Returns the newly selected rating value.

Note

You can listen to the rating-changed event to react whenever the selected rating value changes.
The event provides the updated rating value through the event.detail object, allowing you to handle the result in your application logic (for example, saving the rating or updating the UI).

el.addEventListener("rating-changed", (event) => {
  console.log(event.detail.value);
});