Rating

The Ignite UI for React Rating is a form-associated component that lets users view and select a score on a scale of stars or custom symbols.

The Rating supports half-star and other fractional values, a hover preview, single selection of distinct symbols, and full keyboard input.

Live Demo

Anatomy

The Rating is built from Label and Value, where the Value is the number of the rating scale. The label shows when you set label. Set max to change the number of symbols (5 by default).

The igc-rating element renders the label and a slider that holds the symbols. Without projected symbols, it renders one star for each point of max:

igc-rating
└─ #shadow-root
   ├─ label[part="label"]                    // hidden when label isn't set
   └─ div[part="base"][role="slider"]
      ├─ div[part="symbols"]                 // aria-hidden="true"
      │  └─ slot[name="symbol"]              // projected igc-rating-symbol elements
      │     └─ igc-rating-symbol × max       // default stars when nothing is projected
      │        └─ #shadow-root
      │           ├─ div[part="symbol full"]   // star_filled icon, clipped to the value
      │           └─ div[part="symbol empty"]  // star_outlined icon, clipped to the rest
      └─ label[part="value-label"]
         └─ slot[name="value-label"]         // hidden when the slot is empty

Each igc-rating-symbol renders its default slot in the full part and its empty slot in the empty part.

Getting Started

To use the React Rating, follow the Ignite UI for React Getting Started topic for the basic project setup, then add the component for your target platform.

Install the igniteui-react package:

npm install igniteui-react

Then import the IgrRating wrapper and the theme CSS:

import { IgrRating } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

After registration, render the IgrRating with a label:

<IgrRating label="Rate this product" />

The Rating renders five stars and starts with a value of 0.

Usage

Use the React Rating to collect a score for a product, a service, or an experience, or to show an average score that users can’t change.

Hover Preview

Set hoverPreview to fill the symbols up to the value under the pointer before the user clicks. When the pointer leaves the symbols, the React Rating shows its value again. A read-only or disabled Rating shows no preview.

While the preview is on, the Rating calls onHover with the value under the pointer:

<IgrRating
  hoverPreview={true}
  label="Rate this article"
  onHover={(e: CustomEvent<number>) => setHint(`${e.detail} stars`)}
/>

Reset

By default, a click on the current value keeps the value. Set allowReset to reset the React Rating to 0 when the user clicks the current value again.

<IgrRating allowReset={true} label="Rate this song" />

Read-Only

Set readOnly to show a score that users can’t change, such as the average of all reviews. The value can be any number in the range, so a value of 4.3 fills four symbols and 30% of the fifth. A read-only React Rating stays in the tab order, and assistive technology announces it as read-only.

<IgrRating readOnly={true} value={4.3} label="Average rating" />

Layout

The label property renders a visible label above the symbols and names the React Rating for assistive technology. To show custom content next to the symbols, such as the current score, place it in the value-label slot:

<IgrRating value={score} label="Rate this product" onChange={(e: CustomEvent<number>) => setScore(e.detail)}>
  <span slot="value-label">{score} of 5</span>
</IgrRating>

Give every React Rating an accessible name, and describe its value in words that fit the scale.

When the Rating has no visible label, set aria-label on it, or, with igniteui-webcomponents 7.4.1 and later, associate a <label> element with it. Assistive technology reads the value as “3 of 5” by default. Set valueFormat to replace this text: the Rating replaces {0} with the value and {1} with max, which also lets you localize the text.

<IgrRating aria-label="Delivery speed" valueFormat="{0} out of {1} stars" />

Leave label unset to hide the label, or use the value-label slot to show the score.

Interaction States

The React Rating is enabled by default. Set disabled to turn it off:

<IgrRating disabled={true} value={3} label="Rate this product" />

Empty/Full State

The value of the React Rating sets how full its symbols are. A value of 0, the default, shows all symbols empty, and a value equal to max shows all symbols full.

Keep the value in state and update it in the onChange handler:

import { useState } from 'react';
import { IgrRating } from 'igniteui-react';

export default function MovieRating() {
  const [score, setScore] = useState(3);

  return (
    <IgrRating
      value={score}
      max={10}
      label="Rate this movie"
      onChange={(e: CustomEvent<number>) => setScore(e.detail)}
    />
  );
}

Set step to 0.5 to let users select half stars:

<IgrRating step={0.5} value={3.5} label="Rate your stay" />

Size

The Rating is available in three sizes - Small, Medium and Large. The small, medium, and large sizes render 18px, 24px, and 36px symbols, and the React Rating uses the medium size by default. Set the --ig-size CSS variable to --ig-size-small, --ig-size-medium, or --ig-size-large to choose a size. For a size outside these presets, set --ig-rating-symbol-size:

.rating-small {
  --ig-size: var(--ig-size-small);
}

.rating-large {
  --ig-size: var(--ig-size-large);
}

.rating-custom {
  --ig-rating-symbol-size: 3rem;
}

<IgrRating className="rating-large" label="Rate this product" />

Symbols

By default, the React Rating renders star icons. To use other symbols, place one IgrRatingSymbol for each point of the scale inside the Rating. Each rating symbol shows its default slot content in the part of the symbol that the value covers and its empty slot content in the rest, so fill both slots, even with the same content. The number of rating symbols sets max, and the Rating ignores the max that you set.

The following rating uses registered heart icons. Register the icons first, as described in the Icon topic:

import { IgrIcon, IgrRating, IgrRatingSymbol } from 'igniteui-react';

<IgrRating label="Rate this recipe">
  {[1, 2, 3, 4, 5].map((i) => (
    <IgrRatingSymbol key={i}>
      <IgrIcon name="favorite" collection="material" />
      <IgrIcon name="favorite_border" collection="material" slot="empty" />
    </IgrRatingSymbol>
  ))}
</IgrRating>

The Rating colors icons and text with the full and empty symbol colors of the theme. It renders content other than an Icon in the empty slot in grayscale, so the same emoji in both slots looks selected or empty.

Single Selection

Set single to show only the selected symbol as full. Use single selection with symbols that each stand for one distinct value, such as a scale of faces. In single selection, the React Rating uses a step of 1 and rounds a fractional value up.

const faces = ['😣', '😔', '😐', '🙂', '😆'];

<IgrRating single={true} label="How was your experience?">
  {faces.map((face) => (
    <IgrRatingSymbol key={face}>
      <span>{face}</span>
      <span slot="empty">{face}</span>
    </IgrRatingSymbol>
  ))}
</IgrRating>

Forms

The React Rating is a form-associated element. Inside a <form>, it submits its value as text under its name.

<form
  onSubmit={(e) => {
    e.preventDefault();
    console.log(new FormData(e.currentTarget).get('score'));
  }}
>
  <IgrRating name="score" label="Rate your stay" />
  <button type="submit">Send</button>
</form>

The Rating has no required validation. To require a score, check that the value is greater than 0 before you submit the data.

Do/Don’t

The star is a very recognizable ranking symbol, and people may not associate other symbols with a rating scale. If you replace the star with a custom symbol, make sure that its purpose is clear. Avoid colors with poor contrast, like similar shades of the same color or combinations that create chromatic aberrations. The Icons selections should be emphasized and should have a good visual distinct appearance.

Properties

The React Rating exposes the following properties. See the API reference for the complete type definitions.

Methods

The React Rating exposes the following methods. The step methods change the value without emitting a change event.

Events

The React Rating emits the following events. It doesn’t emit them when you set the value or call a method.

Styling

The React Rating takes its colors and its symbol size from the theme. Change them with the following CSS variables:

The igc-rating element exposes the following CSS parts:

The igc-rating element exports the symbol, full, and empty parts of its default stars only. To style projected rating symbols, use the symbol, full, and empty parts of the igc-rating-symbol element.

Sass Theming

Create a theme with the rating-theme function and include it with the tokens() mixin. The function accepts parameters such as $symbol-full-color, $symbol-empty-color, $label-color, and $symbol-size, and the mixin emits the matching --ig-rating-* variables in the scope where you include it.

The Sass functions come from the igniteui-theming package. See the Theming topic for the Sass setup.

@use "igniteui-theming" as *;

$custom-rating-theme: rating-theme(
  $symbol-full-color: #e41c77,
  $symbol-empty-color: #a9b8cc,
  $label-color: #344b65
);

:root {
  @include tokens($custom-rating-theme);
}

CSS Variables

Set the CSS variables on a Rating or on a container when you need local styling without a Sass build step, and use the CSS parts for other styles:

igc-rating {
  --ig-rating-symbol-full-color: #e41c77;
  --ig-rating-symbol-empty-color: #a9b8cc;
}

igc-rating::part(label) {
  font-weight: 600;
}

igc-rating-symbol::part(empty) {
  opacity: 0.6;
}

Styling with Tailwind

You can style the React Rating with Tailwind arbitrary properties that set its CSS variables. Make sure to set up Tailwind first:

<IgrRating
  label="Rate this product"
  className="[--ig-rating-symbol-full-color:#7B9E89] [--ig-rating-symbol-size:2rem]"
/>

Accessibility

The React Rating is a slider: users reach it with the Tab key, change its value with the arrow keys, and hear the value through its ARIA attributes.

Keyboard Interaction

The React Rating is a single tab stop, because only the slider element inside it, the base part, receives focus. A disabled Rating leaves the tab order. A read-only Rating stays in the tab order but ignores the following keys, so they keep their default browser actions, such as page scrolling.

The React Rating handles these keys on keydown:

• It prevents their default action, so the arrow keys, Home, and End don’t scroll the page while the Rating has focus.
• A key that you hold repeats its action.
• A key that you press together with Shift, Ctrl, Alt, or Meta does nothing.
• The value stays between 0 and the maximum value. A key that would move the value past a bound keeps the value and emits no event.
• Each key that changes the value emits the change event.

With a pointer, a click selects the value under the pointer, rounded up to the next step. A read-only or disabled Rating ignores clicks.

Screen Readers / ARIA

The React Rating renders one focusable element, the base part, with the slider role. Its tabindex is 0, or -1 when the Rating is disabled, and it carries the following value attributes:

With igniteui-webcomponents 7.3.0 and later, the slider also sets aria-disabled and aria-readonly to expose the disabled and read-only states. With 7.4.1 and later, the slider takes its accessible name from the first of the following:

1. The aria-labelledby attribute of the host.
2. A <label> element that is bound through for, or that wraps the Rating. A click on the label focuses the slider.
3. The label property, which renders a visible label that the slider references through aria-labelledby.
4. The aria-label attribute of the host. The slider ignores it when the label property is set.

The React Rating also behaves as follows for assistive technology:

• The symbols part sets aria-hidden="true", so the symbols, including projected icons and emoji, are hidden and don’t need text alternatives. The value reaches assistive technology only through aria-valuenow and aria-valuetext.
• The value-label slot renders inside the slider. Screen readers read the value from aria-valuetext, so describe the value with valueFormat rather than with the slot content.
• The Rating doesn’t use a live region. A changed value reaches assistive technology only through the slider attributes.
• The Rating doesn’t set aria-invalid, so a custom validation message isn’t exposed as an invalid state.

Accessibility Compliance

Infragistics documents Ignite UI for React accessibility support for Section 508 and WCAG 2.1 guideline areas in the Accessibility Compliance topic.

Your responsibilities:

• Name every Rating with the label property, an associated <label> element, or aria-label. See Layout.
• Set valueFormat when “3 of 5” doesn’t describe the scale, or when the page uses another language.
• With custom symbols, make the full and the empty symbols differ in shape or fill, not only in color, and keep a contrast ratio of at least 3:1 against the background, as 1.4.11 Non-text Contrast requires.
• When you restyle the base part, keep a visible focus indicator.
• Keep the pointer targets large enough. Each value is a target as wide as one symbol, or half a symbol with a step of 0.5. The small size renders 18px symbols, below the 24 by 24 CSS pixels of 2.5.8 Target Size (Minimum), so prefer the medium or the large size for pointer and touch input.
• Don’t put information only in the hover preview, because keyboard users don’t see it.
• When you validate the rating with a custom validation message, also show the message as text next to the Rating, as 3.3.1 Error Identification requires, because the Rating doesn’t set aria-invalid.

Differences from the WAI-ARIA slider pattern:

• Home sets the value to one step instead of to aria-valuemin, which is 0. Use Arrow Down to reach 0.
• The Rating doesn’t support Page Up and Page Down, which the pattern lists as optional keys.

Troubleshooting

Use these answers when a React Rating doesn’t behave as expected.

Why doesn’t the change event fire when I set the value?

The React Rating emits the change event only for user input: a click or a key. Setting the value in code, or calling the step methods, changes the value without the event, so update your own state where you set the value.

Why doesn’t a click on the current value reset the rating?

The React Rating keeps the value on a click on the current value, unless you set allowReset. Before igniteui-webcomponents 4.7.0, a click on the current value always reset the rating; set allowReset to keep that behavior after an upgrade.

Why doesn’t the hover event fire?

The React Rating emits the hover event only while hoverPreview is on, and not when the Rating is read-only or disabled. Set hoverPreview to receive the event.

API References

Dependencies

The React Rating requires a theme to apply its colors and symbol sizes. See the framework-specific setup in Getting Started.

Additional Resources

The following resources provide more React Rating guidance and project support:

• Rating - Design System Component
• Ignite UI for React Forums
• Ignite UI for React GitHub

Related Components

The React Rating collects a score on a scale of symbols. Use these components when the input needs a different form:

• Slider - Use Slider when users pick a precise number from a continuous range, such as a price or a volume.
• Radio Group - Use Radio Group when each option needs a text label, such as Poor, Fair, and Good.
• Icon - Use Icon to draw the custom symbols of a Rating.

FAQ

These questions cover common React Rating setup, accessibility, and usage scenarios.