> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/rating.md).

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

```html
<!-- 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>
```

```js
// 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.

```html
<!-- 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`            |          |
| `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.                        |

### 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 <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/rating.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.