Rating

<wa-rating> Stable Since 2.0

Ratings display a numeric score as a row of selectable symbols, typically stars. Use them to capture quick feedback or show an average rating for a product or piece of content.

This component works with standard <form> elements. Please refer to the section on form controls to learn more about form submission and client-side validation.

Examples

Link to This Section

Labels

Link to This Section

Ratings are commonly identified contextually, so labels aren't displayed. However, you should always provide one for assistive devices using the label attribute.

Maximum Value

Link to This Section

Ratings are 0-5 by default. To change the maximum possible value, use the max attribute.

Precision

Link to This Section

Use the precision attribute to let users select fractional ratings.

Sizing

Link to This Section

Use the size attribute to adjust the size of the rating.





For more granular sizing, you can use the font-size property.

Readonly

Link to This Section

Use the readonly attribute to display a rating that users can't change.

Disabled

Link to This Section

Use the disabled attribute to disable the rating.

Detecting Hover

Link to This Section

Use the wa-hover event to detect when the user hovers over (or touch and drag) the rating. This lets you hook into values as the user interacts with the rating, but before they select a value.

The event has a payload with phase and value properties. The phase property tells when hovering starts, moves to a new value, and ends. The value property tells what the rating's value would be if the user were to commit to the hovered value.

Custom Icons

Link to This Section

You can provide custom icons by passing a function to the getSymbol property.

Value-based Icons

Link to This Section

You can also use the getSymbol property to render different icons based on value and/or whether the icon is currently selected.

Required

Link to This Section

Use the required attribute to make the rating mandatory. The form will not submit if the user hasn't selected a value.



Submit

Custom Validity

Link to This Section

Use the setCustomValidity() method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.



Submit

Form Submission

Link to This Section

Ratings can be used in forms just like native form controls. The rating's name and value will be included in the form data when submitted.



Submit Reset

Importing

Link to This Section

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

CDN npm Self-Hosted React

Import this component directly from the CDN:

import 'https://ka-f.webawesome.com/[email protected]/components/rating/rating.js';

After installing Web Awesome via npm, import this component:

import '@awesome.me/webawesome/dist/components/rating/rating.js';

If you're self-hosting Web Awesome, import this component from your server:

import './webawesome/dist/components/rating/rating.js';

To import this component for React 18 or below, use the following code:

import WaRating from '@awesome.me/webawesome/dist/react/rating/index.js';

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Methods

Link to This Section

Learn more about methods.

Events

Link to This Section

Learn more about events.

CSS custom properties

Link to This Section

Learn more about CSS custom properties.

CSS parts

Link to This Section

Learn more about CSS parts.

Dependencies

Link to This Section

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

Need a hand? Report a bug Ask for help
    No results