Rating 21.18.0

A score out of a few stars, to give or to show. A row of star icons is five tab stops with no names; what it is, is one choice out of five. Interactive, the stars are drawn over native radios, so the keyboard and the announcement come from the platform. Read-only, it is a picture with a number in it, named in words.

Overview

import { RatingComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [RatingComponent],
})

Bind the value two-way to give a rating; set readonly to show one:

<div>
  <gog-rating label="Your rating" [(value)]="score" />
  <p>value: {{ score() }}</p>
</div>
<div>
  <gog-rating label="Average" readonly [value]="4.7" />
</div>

Examples

Sizes

Stars of 16 to 32px, interactive beside read-only. The pressable box around a star never falls under 24x24, whatever the theme's density does to the star.

@for (size of sizes; track size) {
  <div>
    <span>{{ size }}</span>
    <gog-rating ariaLabel="Score" [size]="size" [value]="3" />
    <gog-rating readonly [size]="size" [value]="3.5" />
  </div>
}

Read-only, fractional values

The value may be fractional. The stars draw to the nearest half — the precision an eye can read off a star — and the accessible name keeps the real value: "Rated 3.7 out of 5". null is "Not rated". A half star is mirrored under dir="rtl".

1.2

2.5

3.7

4.3

null

@for (value of values; track $index) {
  <div>
    <span>{{ value ?? 'null' }}</span>
    <gog-rating readonly size="sm" [value]="value" />
  </div>
}

max and clearable

max sets how many stars. With clearable, a press on the chosen star — or Space on it — clears the rating to null, which native radios cannot do; without it, a rating once given can only change. Hover previews the score a press would give.

<div>
  <gog-rating label="Out of ten" [max]="10" size="sm" [(value)]="outOfTen" />
  <p>value: {{ outOfTen() }}</p>
</div>
<div>
  <gog-rating label="Press the chosen star again" clearable [(value)]="clearable" />
  <p>value: {{ clearable() }}</p>
</div>

States

Default, with an error, and disabled.

<gog-rating label="Your stay" [value]="3" />
<gog-rating label="Your stay" [value]="3" errorMessage="Rate your stay" />
<gog-rating label="Your stay" [value]="3" disabled />

Forms

A ControlValueAccessor holding a number | null, with errorDisplay and GOG_CONFIG.control.size like every field.

<div>
  <gog-rating
    label="Rate the delivery"
    errorMessage="Pick a rating"
    errorDisplay="auto"
    [formControl]="delivery"
  />
  <p>value {{ delivery.value }} · touched {{ delivery.touched }} · valid {{ delivery.valid }}</p>
</div>
<div>
  <gog-button variant="secondary" size="sm" (gogClick)="delivery.markAsTouched()">
    markAsTouched()
  </gog-button>
  <gog-button variant="ghost" size="sm" (gogClick)="delivery.reset()">reset()</gog-button>
</div>

Accessibility

Interactive, a radio group; read-only, an image whose name is the score.

One tab stop — a radiogroup named by label (or ariaLabel); Tab enters it on the chosen star and the arrow keys move the rating.
Named stars — each radio is "3 stars" (GOG_CONFIG.labels.ratingStar), read with its position: "3 stars, 3 of 5".
Clearing from the keyboard — with clearable, Space on the chosen star clears it, and Space again chooses it back.
Read-only — one role="img", named "Rated 4.7 out of 5" (ratingValue), with the label in front when there is one. Use it for a displayed average, not disabled.

API Reference

gog-rating inputs

Name	Type	Default	Description
`value`	`number \| null (model)`	`null`	The score, two-way; null is not rated. Also what an attached form control holds.
`max`	`number`	`5`	How many stars.
`readonly`	`boolean`	`false`	A picture of the score rather than a control; the value may be fractional.
`clearable`	`boolean`	`false`	A press on the chosen star, or Space on it, clears the rating.
`label`	`string`	`''`	The group’s name, shown above the stars.
`ariaLabel`	`string`	`''`	Names the group when there is no label.
`errorMessage`	`string`	`''`
`errorDisplay`	`GogErrorDisplay \| undefined`	`'manual'`	Unset, GOG_CONFIG.control.errorDisplay.
`disabled`	`boolean`	`false`
`size`	`GogSize \| undefined`	`'md'`	Unset, GOG_CONFIG.control.size.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

GOG_CONFIG.control.size
GOG_CONFIG.control.errorDisplay
GOG_CONFIG.labels.ratingStar — a formatter: (value, max) => string, each star’s name
GOG_CONFIG.labels.ratingValue — a formatter: (value, max) => string, the read-only name

Styling Tokens

Every CSS custom property the rating paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

Token	Description
`--gog-rating-font-family / -gap`	The typeface, and the space between label, stars and error.
`--gog-rating-label-font-family / -label-font-size / -label-line-height / -label-font-weight / -label-color / -label-text-transform / -label-letter-spacing`	The label — the field label’s tokens by reference.
`--gog-rating-xsm-star-size / -sm-star-size / -md-star-size / -lg-star-size / -slg-star-size`	The star at each size: 16, 20, 24, 28 and 32px.
`--gog-rating-star-padding / -star-radius / -glyph-line-height`	The least room around a star (raised so the pressable box is never under 24x24), its focus corner, and the glyph’s own box.
`--gog-rating-empty-color / -fill-color`	An empty star’s outline (the control boundary colour, 3:1) and a filled one (the accent).
`--gog-rating-focus-ring-width / -focus-ring-offset / -focus-ring-color`	The ring round the focused star.
`--gog-rating-error-color / -error-font-size / -error-line-height`	The error line.
`--gog-rating-disabled-opacity`	The whole rating, disabled.