Rating

avonni-rating

Lets users view or set a rating by selecting from a row of icons such as stars.

Overview

Rating is a Lightning Web Component that lets users rate something on a scale, using icons such as stars or a plain numeric range.

Use it in your own Lightning Web Components to capture satisfaction scores, difficulty levels, or any value within a min/max range. You control the icon, size, scale bounds, selection behavior, label placement, and validation—all through the component's attributes.

Use Cases

• Satisfaction surveys: Capture a 1–5 star experience rating.
• Product reviews: Let users rate items on a custom scale.
• Difficulty levels: Collect a single-pick rating on a labeled scale.
• Read-only displays: Show an existing score without allowing edits.
• Numeric scales: Render a 1–10 scale without icons.

---

Variant Guidelines

Variant	Use Case
standard	Label above the rating (default).
label-stacked	Label stacked above the field.
label-inline	Label horizontally aligned with the rating.
label-hidden	Hides the label but keeps it for assistive tech.

---

Use Case Examples

Example 1: Star satisfaction rating

Scenario: Capture a required 1–5 star experience rating and react to the selection.

<!-- experienceRating.html -->
<template>
    <avonni-rating
        label="Rate your experience"
        field-level-help="Select a star to rate from 1 to 5."
        icon-name="utility:favorite"
        icon-size="large"
        min="1"
        max="5"
        value={value}
        selection="continuous"
        variant="label-stacked"
        required
        onchange={handleChange}
    ></avonni-rating>
</template>

// experienceRating.js
import { LightningElement } from 'lwc';

export default class ExperienceRating extends LightningElement {
    value = '4';

    handleChange(event) {
        this.value = event.detail.value; // the selected rating
    }
}

Result: A five-star rating labeled "Rate your experience"; selecting a star fires change with the chosen value.

Example 2: Read-only numeric scale

Scenario: Display an existing 1–10 score without icons and without allowing edits.

<!-- scoreDisplay.html -->
<template>
    <avonni-rating
        label="Difficulty"
        min="1"
        max="10"
        value="7"
        variant="label-stacked"
        value-hidden
        read-only
    ></avonni-rating>
</template>

Result: A read-only 1–10 scale showing the value 7 selected, with the fraction readout hidden.

---

Specifications

Attributes

Name	Description	Type	Default	Required
disabled	If present, the rating component is disabled and users cannot interact with it.	Boolean	false
field-level-help	Help text detailing the purpose and function of the rating component.	String	—
icon-name	The Lightning Design System name of the icon. Specify the name in the format 'utility:favorite' where 'utility' is the category, and 'favorite' is the specific icon to be displayed.	String	—
icon-size	Valid values include x-small, small, medium and large.	String	"large"
label	Label for the rating component.	String	—
max	The maximum acceptable value for the rating component.	Number	5
min	The minimum acceptable value for the rating component.	Number	1
name	Assign a unique ID through the name of the rating component.	String	—
rating-value-labels	Represents the value labels for the rating.	object[]	—
read-only	If present, the rating component is read-only and cannot be edited by users.	Boolean	false
required	If present, the input field must be filled out before the form is submitted.	Boolean	false
required-alternative-text	Alternative text for the required indicator.	String	"Required"
selection	Valid values include continuous and single.	String	"continuous"
validity	Represents the validity states that an element can be in, with respect to constraint validation.	String	—
value	Specifies the value of the rating.	String	—
value-hidden	Hide the rating fraction representation (e.g. "4/5" rating).	Boolean	false
variant	The variant changes the appearance of an input field. Accepted variants include standard, label-inline, label-hidden, and label-stacked. This value defaults to standard, which displays the label above the field. Use label-hidden to hide the label but make it available to assistive technology. Use label-inline to horizontally align the label and input field. Use label-stacked to place the label above the input field.	String	"standard"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
checkValidity	Checks if the input is valid.
focus	Set the focus on the rating.
reportValidity	Displays the error messages. If the input is valid, reportValidity() clears displayed error messages.
setCustomValidity	Sets a custom error message to be displayed when a form is submitted.	message	String	The string that describes the error. If message is an empty string, the error message is reset.
showHelpMessageIfInvalid	Displays error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when checkValidity() is called.

Custom Events

blur

The event fired when the focus is removed from the rating.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the value change..

The change event returns the following parameters.

Parameter	Type	Description
value	string	Value of the selected rating.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the focus is set on the rating.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

blur

The event fired when the focus is removed from the rating.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the value change..

The change event returns the following parameters.

Parameter	Type	Description
value	string	Value of the selected rating.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the focus is set on the rating.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-rating-button-color-background	color	#ffffff
--avonni-rating-button-color-background-disabled	color	#ffffff
---avonni-rating-button-color-background-disabled-selected	color	#c9c7c5
--avonni-rating-button-color-background-hover	color	#014486
--avonni-rating-button-color-background-selected	color	#0176d3
--avonni-rating-button-color-border	color	#0176d3
--avonni-rating-button-color-border-disabled	color	#c9c9c9
---avonni-rating-button-color-border-disabled-selected	color	#c9c7c5
--avonni-rating-button-color-border-hover	color	#014486
--avonni-rating-button-color-border-selected	color	#0176d3
--avonni-rating-button-text-color	color	#0176d3
--avonni-rating-button-text-color-disabled	color	#c9c7c5
--avonni-rating-button-text-color-disabled-selected	color	#ffffff
--avonni-rating-button-text-color-hover	color	#ffffff
--avonni-rating-button-text-color-selected	color	#ffffff
--avonni-rating-header-text-color	color	#3e3e3c
--avonni-rating-header-font-size	font	0.75rem
--avonni-rating-header-font-style	font	normal
--avonni-rating-header-font-weight	font	400
--avonni-rating-icon-color-foreground	color	#c9c7c5
--avonni-rating-icon-color-foreground-disabled	color	#c9c7c5
--avonni-rating-icon-color-foreground-disabled-selected	color	#747474
--avonni-rating-icon-color-foreground-hover	color	#014486
--avonni-rating-icon-color-foreground-selected	color	#0176d3
--avonni-rating-value-text-color	color	#080707
--avonni-rating-value-font-size	font	0.8125rem
--avonni-rating-value-font-style	font	normal
--avonni-rating-value-font-weight	font	400
--avonni-rating-button-color-background-disabled-selected	color	#c9c7c5
--avonni-rating-button-color-border-disabled-selected	color	#c9c7c5
--avonni-rating-button-radius-border	dimension	—
--avonni-rating-button-sizing-border	sizing	1px
--avonni-rating-button-styling-border	string	solid

Key Considerations

• Scale bounds: value must fall between min and max.
• Icons optional: Omit icon-name to render a plain numeric scale.
• Selection mode: continuous highlights all units up to the value; single highlights just the picked unit.
• States: read-only shows a value but blocks editing; disabled greys out the whole control.
• Validation: Use required plus methods like reportValidity() to enforce a selection on submit.
• Best Practice: Set min, max, and a clear label so the scale and its purpose are obvious. Provide an icon-name for visual ratings, or omit it for a plain numeric scale.

---

Troubleshooting Common Issues

• No icons rendering: Provide a valid icon-name in category:name form, e.g. utility:favorite.
• Value not selectable: Confirm the rating is not read-only or disabled and the value is within min–max.
• Change not firing: Verify the onchange handler is wired and the control is interactive.
• If issues persist: Contact our support team at [email protected] for assistance.