# Rating

The Rating component allows users to provide a rating by selecting a number of icons (typically stars, but other icons can be used). It's a visually engaging way to collect user feedback or represent rating data.

## Overview

The Rating component is an *input* component that displays a series of icons, allowing the user to click on an icon to select a rating value. The component can be used in both read-only and interactive modes.

### Key Features

* Customizable Icon: Choose the icon to represent the rating (stars are common, but many other options are available).
* Configurable Scale: Set the minimum and maximum rating values.
* Read-Only/Disabled Modes: Display ratings without allowing user input.
* Interactions: Trigger actions when the user changes the rating.
* Continuous Selection: select multiple icons at once by sliding on the rating component.

## Setting up your Rating

Select the Rating component on the canvas to access its properties in the Properties Panel (right panel).

### Basic Properties

These properties control the fundamental data and labeling of the Rating component.

* **API Name:** (Text) A *unique* identifier for this specific Rating component within your Dynamic Component. Use a descriptive name (e.g., `ProductRating`, `CustomerSatisfactionRating`). This name is used for referencing the component in interactions and formulas.
* **Label:** (Text) The text label displayed above or next to the rating icons. Example: "Rate this Product:", "Your Satisfaction:", "Overall Rating:".
* **Field Level Help:** (Text, Optional) Help text displayed next to the label, providing additional context or instructions.
* **Value:** (Number) *This is the most important property for interacting with the Rating component.* It holds the *currently selected rating value* (e.g., 3, 5, 1).
  * **Data Binding:** You should *bind* this property to a *Number* Variable resource. This allows you to:
    * Store the user's selected rating.
    * Use the rating value in other parts of your component (e.g., in filters, formulas, or interactions).
    * Set a *default* rating by initializing the Variable resource.

### Appearance Properties

These properties control the visual presentation of the Rating component

* **Icon Name:** (Text) The name of the icon to use for the rating. Avonni uses Salesforce SLDS icons. Common examples:
  * `utility:star` (for star ratings)
  * `utility:like` (for thumbs-up/thumbs-down)
  * `utility:smiley_and_people` (for smiley faces)
  * See the \[Salesforce SLDS Icon Documentation]\(*Insert Link Here*) for a complete list of available icons.
  * You can also *bind* this property to a Variable or Formula resource to dynamically change the icon based on data or conditions.
* **Variant:** (Text - Select from options) Controls the visual style and positioning of the *label*:
  * `standard`: Label is displayed above the rating icons.
  * `label-inline`: Label is displayed to the left of the rating icons.
  * `label-stacked`: Label is displayed above the rating icons (similar to `standard`, but might have different spacing/styling).
  * `label-hidden`: The label is hidden. Use this only if the purpose of the rating is clear from context or other UI elements.
* **Min:** (Number) The minimum allowed rating value. This is usually `0` or `1`. Check the component's specific documentation for the default.
* **Max:** (Number) The maximum allowed rating value. This determines the *total number of icons displayed*. The default is often `5`.
* **Value Hidden:** (Boolean - Checkbox) If enabled, the *numerical* rating value is hidden, and only the icons are displayed. If disabled, the numerical value might be displayed alongside the icons (depending on the component's styling).

### Behavior Properties

These properties control how the user interacts with the Rating component and its overall behavior

* **Selection:** (Text - Select from options) Controls how the user can select a rating:
  * `continuous`: The user can select a value by sliding on the component.
  * `single`: The user can select one value at a time.
* **Required:** (Boolean - Checkbox) If enabled, the user *must* select a rating before they can perform other actions (e.g., submit a form). You'll typically use this in conjunction with validation logic.
* **Read Only:** (Boolean - Checkbox) If enabled, the user can *see* the rating, but they *cannot change* it. This is useful for displaying existing ratings.
* **Disabled:** (Boolean - Checkbox) If enabled, the Rating component is entirely disabled and cannot be interacted with. This visually indicates that the rating is not applicable or cannot be changed.
* **Visible:** (Boolean) Controls whether the Rating component is visible on the page. You can bind this to a Boolean Variable or Formula for dynamic visibility

### Interactions

The Rating component supports the **On Change** interaction. This interaction is triggered whenever the user changes their rating selection.

* **On Change:** Use this interaction to:
  * **Set Variable Value:** Update a Variable resource with the new rating value (from `@RatingComponent.value`). This is the *most common* use case.
  * **Execute Flow:** Launch a Flow, passing the new rating as an input variable.
  * **Refresh Data:** Update other components on the page based on the new rating.
  * **Show Toast:** Display a confirmation message.

Within the "On Change" interaction, you can access the currently selected rating value using:

`@RatingComponent.value`

(Replace `RatingComponent` with the actual *API Name* of your Rating component). This will return a *Number*.

## Examples

### Example 1: Basic Rating Input

1. Add a Rating component.
2. Set the `Label` to "Rate this Product:".
3. Set the `Icon Name` to `utility:star`.
4. Set the `Max` to `5`.
5. Create a Number Variable resource named `productRating`.
6. Bind the Rating component's `Value` property to `{!productRating}`.

This creates a basic 5-star rating input. The user's selection will be stored in the `productRating` variable.

### Example 2: Read-Only Display of Average Rating

1. Add a Rating component.
2. Set the `Label` to "Average Rating:".
3. Set the `Icon Name` to `utility:star`.
4. Set the `Max` to `5`.
5. Set the `Read Only` to be true.
6. Create a variable, or formula, named `averageRating`.
7. Bind the Rating component's `Value` property to `{!averageRating}`.
8. Use a `Get Records` on load interaction to get the value from Salesforce.

This will *display* the average rating (assuming you have a way to calculate and store it in the `averageRating` variable), but the user won't be able to change it.

### Example 3: On Change Interaction

1. Follow steps of Example 1 to create the Rating.
2. Select the rating component.
3. Go to the interactions, and select the `On Change`
4. Add a `Show Toast` action that confirms the user's rating using the value of your `Rating` Component..
5. Important Considerations
   * Data Binding: The `Value` property is crucial. Bind it to a Number Variable to store the user's selection.
   * Read Only vs. Disabled: Understand the difference. `Read Only` prevents changes but still shows the component; `Disabled` greys out the component and prevents all interaction.
   * Interactions: Use the "On Change" interaction to make your Rating component dynamic and responsive.
   * Accessibility: Provide a clear `Label`.
   * **Variant**: Adapts the label display.

In Summary: The rating component is a simple way to collect and display ratings from users, using a visual and intuitive icon-based interface


---

# Agent Instructions: 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:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/rating.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.