Rating

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

In Angular, the Rating is the igc-rating web component from igniteui-webcomponents. Bind it to Angular forms with the IgcFormControlDirective.

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 Angular Rating, follow the Ignite UI for Angular Getting Started topic for the basic project setup, then add the component for your target platform.

If your project doesn’t use Ignite UI for Angular yet, run ng add igniteui-angular. Then install the igniteui-webcomponents package, which provides the Rating:

npm install igniteui-webcomponents

Register the IgcRatingComponent, and add CUSTOM_ELEMENTS_SCHEMA to the Angular component that renders igc-rating:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { defineComponents, IgcRatingComponent } from 'igniteui-webcomponents';

defineComponents(IgcRatingComponent);

@Component({
    selector: 'app-product-rating',
    template: '<igc-rating label="Rate this product"></igc-rating>',
    schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ProductRatingComponent {}

The Ignite UI for Angular theme styles igc-rating, so the Rating follows the theme that you include with the theme() mixin.

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

Usage

Use the Angular 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 Angular Rating shows its value again. A read-only or disabled Rating shows no preview.

While the preview is on, the Rating emits igcHover with the value under the pointer:

<igc-rating hover-preview label="Rate this article" (igcHover)="onHover($event)"></igc-rating>

public hint = '';

public onHover(event: Event) {
    this.hint = `${(event as CustomEvent<number>).detail} stars`;
}

Reset

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

<igc-rating allow-reset label="Rate this song"></igc-rating>

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 Angular Rating stays in the tab order, and assistive technology announces it as read-only.

<igc-rating readonly value="4.3" label="Average rating"></igc-rating>

Layout

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

<igc-rating [value]="score" label="Rate this product" (igcChange)="onScoreChange($event)">
  <span slot="value-label">{{ score }} of 5</span>
</igc-rating>

Give every Angular 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.

<igc-rating aria-label="Delivery speed" value-format="{0} out of {1} stars"></igc-rating>

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

Interaction States

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

<igc-rating disabled value="3" label="Rate this product"></igc-rating>

Empty/Full State

The value of the Angular 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.

Bind the value as a property, and update it in the igcChange handler:

<igc-rating [value]="score" max="10" label="Rate this movie" (igcChange)="onScoreChange($event)"></igc-rating>

public score = 3;

public onScoreChange(event: Event) {
    this.score = (event as CustomEvent<number>).detail;
}

Set step to 0.5 to let users select half stars:

<igc-rating step="0.5" value="3.5" label="Rate your stay"></igc-rating>

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 Angular 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;
}

<igc-rating class="rating-large" label="Rate this product"></igc-rating>

Symbols

By default, the Angular Rating renders star icons. To use other symbols, place one igc-rating-symbol element 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 heart icons that you register with registerIconFromText from igniteui-webcomponents. Use igc-icon in the rating symbols, because the Rating sizes igc-icon elements to the symbol size:

<igc-rating label="Rate this recipe">
  @for (i of [1, 2, 3, 4, 5]; track i) {
    <igc-rating-symbol>
      <igc-icon name="favorite" collection="material"></igc-icon>
      <igc-icon name="favorite_border" collection="material" slot="empty"></igc-icon>
    </igc-rating-symbol>
  }
</igc-rating>

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 Angular Rating uses a step of 1 and rounds a fractional value up.

<igc-rating single label="How was your experience?">
  @for (face of faces; track face) {
    <igc-rating-symbol>
      <span>{{ face }}</span>
      <span slot="empty">{{ face }}</span>
    </igc-rating-symbol>
  }
</igc-rating>

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

Forms

To bind the Rating with ngModel or formControlName, Angular needs an implementation of its ControlValueAccessor interface. Ignite UI for Angular provides it as the standalone IgcFormControlDirective, which attaches to igc-rating elements with ngModel or formControlName. Import it together with FormsModule or ReactiveFormsModule:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { IgcFormControlDirective } from 'igniteui-angular/directives';
// import { IgcFormControlDirective } from '@infragistics/igniteui-angular/directives'; for licensed package

@Component({
    selector: 'app-review-form',
    template: `
        <form>
            <igc-rating name="userRating" [(ngModel)]="review.rating" label="Your rating"></igc-rating>
        </form>
    `,
    imports: [FormsModule, IgcFormControlDirective],
    schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ReviewFormComponent {
    public review = { rating: 0 };
}

With reactive forms, bind the Rating with formControlName:

<form [formGroup]="reviewForm">
  <igc-rating formControlName="rating" label="Your rating"></igc-rating>
</form>

The directive updates the model on igcChange, marks the control as touched when the Rating loses focus, and disables the Rating when you disable the form control.

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 Angular Rating exposes the following properties. See the API reference for the complete type definitions.

Methods

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

Events

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

Styling

The Angular 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.

@use "igniteui-angular/theming" as *;

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

:host {
  @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 Angular Rating with Tailwind arbitrary properties that set its CSS variables. Make sure to set up Tailwind first:

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

Accessibility

The Angular 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 Angular 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 Angular 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 Angular 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 Angular 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 Angular 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 Angular Rating doesn’t behave as expected.

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

The Angular 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 Angular 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 Angular 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 Angular Rating requires a theme to apply its colors and symbol sizes. See the framework-specific setup in Getting Started.

The Rating requires the igniteui-webcomponents package, and Angular forms binding requires the IgcFormControlDirective. The theme() mixin of Ignite UI for Angular includes the igc-rating styles unless you exclude igc-rating through its $exclude parameter.

Additional Resources

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

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

Related Components

The Angular 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 Angular Rating setup, accessibility, and usage scenarios.