Rating

Import

import { Rating } from '@envsemble/envui';

Usage

A Rating shows value, from 0 to max, such as 4.5, rounded to the nearest half star and kept within the scale; a value that is not a number shows no stars. max is the number of stars, 5 by default, as a whole number. showValue shows the rounded value as a number before the stars, in tabular digits and the locale's number format. A Rating only shows a rating: to ask for one, use a separate input, such as a RadioGroup.

Scales.tsx

import { Rating, Column } from '@envsemble/envui';

export default function Scales() {
  return (
    <Column gap={3} align="start">
      <Rating value={4} />
      <Rating value={3.5} showValue />
      <Rating value={7} max={10} showValue />
    </Column>
  );
}

Name and language

The stars are one image, named such as 4.5 out of 5 stars, or by formatLabel for one rating, which receives the shown value and the number of stars. The number from showValue is hidden from assistive technology, since the name says it.

const messages = {
  rating: {
    label: ({ value, max }: { value: string; max: string }) => `Rated ${value} out of ${max} stars`,
  },
};

<EnvUIProvider messages={messages}>
  <Rating value={4.5} showValue />
</EnvUIProvider>;

Composition

The parts are the number, env-rating-value, and the stars, env-rating-stars, each an env-rating-star with data-fill, full or half, and a half star's filled half, env-rating-star-half. Say beside it whose rating it is and how many people gave it.

Customize

--env-color-fg-rating-star is the filled stars' gold, a token with a value for each theme and contrast; the empty stars take --env-color-border-default.

Accessibility

You provide

Text that says whose rating it is.
A separate input, such as a RadioGroup, where people give a rating.

envUI provides

The stars as one image named by the rating, such as 4.5 out of 5 stars.
The number from showValue hidden, since the name says it.
No focus: a rating handles no keys.

Props

A read-only rating, such as a review score: stars filled to the value in half steps in their own gold, with an optional number before them, named once for assistive technology as an image, such as "4.5 out of 5 stars". It shows a rating; it does not ask for one.

Prop	Type	Description
`value`required	`number`	The rating, from 0 to max, such as 4.5. It shows rounded to the nearest half star, kept within 0 and max; a value that is not a number, such as NaN, shows no stars filled.
`max`Default `5`	`number`	How many stars the scale has, as a whole number, such as 10. A fraction rounds to the nearest whole star; a value below 1 or not a number shows 5 stars.
`showValue`Default `false`	`boolean`	Shows the rating as a number before the stars, such as 4.5, in tabular digits and the locale's number format, such as 4,5 in German. The number is the rounded value the stars show, and it is hidden from assistive technology, since the stars' name already says it.
`formatLabel`Default `'{value} out of {max} stars'`	`(value: number, max: number) => string`	Writes the accessible name of the stars from the shown value, rounded to a half star, and the number of stars. It overrides EnvUIProvider's `messages.rating.label`, which receives both as text in the locale's number format.

Also accepts the native props of <span>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-rating: The rating.
env-rating-star: One star.
env-rating-star-half: The filled half of a half star.
env-rating-stars: The row of stars.
env-rating-value: The rating as text.
data-fill: full · half on env-rating-star

Strings

EnvUIProvider's messages overrides each, and a component's own label prop wins over it.

messages.rating.label: ({ value, max }) => string Names the rating, such as 4.5 out of 5 stars.

Changelog

1.0.0: The shown number and the name follow the locale, and the name comes from messages.rating.label. Empty stars take the boundary color of controls, at least 3:1 against every surface. Filled stars take a clear gold of their own, --env-color-fg-rating-star, in place of the warning tone.