Rating

import { Rating, RatingInput } from '@uhg-abyss/web/ui/Rating';

rating

hideRating

size

singleStarDisplay

ratingAriaLabel

() => {
  return <Rating />;
};

Read-only rating

Rating distribution

Use the distributionConfig prop to display a rating distribution. This prop accepts an array of objects with type DistributionConfigItem, each representing a star rating and its associated percentage. The href and onClick props can be used to specify a link or button for each star rating. To use one function for all star ratings, use the onDistributionClick prop instead.

DistributionConfigItem {
  starCount: 1 | 2 | 3 | 4 | 5 | number;
  percentage: number;
  href?: string;
  onClick?: (
    event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>
  ) => void;
}

When using a rating distribution, the size of the rating should be set to lg to follow design standards.

The rating distribution can be used to filter reviews by star rating. See the example below for one way to implement this functionality.

Size and star display

Use the size prop to specify the size of the component as lg, sm. The default is set to lg.

Use the singleStarDisplay prop to display a single star instead of the default five stars.

Use the rating prop to provide the rating value. This value will determine how many of the star icons are active and will be displayed next to the icons by default.

To hide the rating number, use the hideRating prop.

Note

If no value is specified, the rating will default to 0.
Decimal numbers are rounded to the nearest half number to determine how many star icons are active.

Reviews configuration

To configure the rest of the reviews, use the prop reviewsConfig. This prop accepts an object with the following structure:

{
  count?: number; // Defaults to 0
  description?: string; // Defaults to "`count` Reviews"
  href?: string;
  onClick?: (event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => void;
}

The following sections, Review description and Href and onClick demonstrate how to use each of these properties.

Review description

Use count to specify the number of reviews. If no value is specified, the count will default to 0. If the value is less than 0, the review count will display as 0.

To not just customize the number, use description to customize the text displaying the review count. The default value is "count Reviews".

Use the separate prop hideReviews to hide the review display.

Href and onClick

Use href and onClick to turn the review display into either a link or a button styled as a link.

Rating ARIA label

Use the ratingAriaLabel prop to override the default ARIA label for the star count. See the Accessibility tab for more information regarding the usage of this field.

Heading level

Use the headingLevel prop to override the default heading of the Rating. The default is 3, but it can be set to different values depending on the application's nested heading structure. To display as a <span> instead, set it to 0.

Interactive rating input

For an interactive rating input, use the RatingInput component. This component is a form input that allows users to select a rating value. This means that properties used by other form inputs can also be applied to this component, such as validators, subtext, hideLabel, and helper.

Further explanation of such props can be found in the TextInput documentation.

useForm (recommended)

Using useForm and FormProvider simplifies form management by providing out-of-the-box validation, form state handling, and performance optimizations, leveraging the power of react-hook-form.

Tip

The default error message when required is true is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form.

useState

Using the useState hook gets values from the component state.

Rating Props

Name	Type	Default	Description
className	string \| undefined		CSS class name to apply to each element within the component
css	CSSProperties \| Partial<Record<"abyss-distribution-container" \| "abyss-rating-text" \| "abyss-rating-root" \| "abyss-rating-value" \| "abyss-rating-star" \| "abyss-rating-distribution-container" \| "abyss-rating-stars-wrapper" \| "abyss-rating-stars-container" \| "abyss-rating-review-action", CSSProperties>> \| undefined		Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string \| undefined		Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean \| undefined	false	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
distributionConfig	DistributionConfigItem[] \| undefined		Optional configuration for displaying rating distribution
headingLevel	0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined	3	The heading level for the rating wrapper. When set to 0, it appears as a <span>
hiddenFrom	Breakpoint \| undefined		When defined, the component is hidden once the screen width reaches the specified breakpoint.
hideRating	boolean \| undefined	false	Hides Rating number
hideReviews	boolean \| undefined	false	Whether to hide the reviews section
onDistributionClick	((starCount: number) => void) \| undefined		Optional callback function executed when a rating distribution is clicked
rating	number \| undefined	0	Rating number
ratingAriaLabel	string \| undefined		Overrides the default ARIA label for Rating
reviewsConfig	ReviewsConfig \| undefined		Reviews configuration object
singleStarDisplay	boolean \| undefined	false	Whether to display a single star or 5 stars
size	"sm" \| "lg" \| "$sm" \| "$lg" \| undefined	'lg'	The size of Rating
slotProps	RatingSlotPropsMap \| undefined		Props to pass to individual internal slots of the component.
visibleFrom	Breakpoint \| undefined		When defined, the component is hidden until the screen width reaches the specified breakpoint.

RatingInput Props

Name	Type	Default	Description
className	string \| undefined		CSS class name to apply to each element within the component
css	CSSProperties \| Partial<Record<"abyss-rating-input-label" \| "abyss-rating-input-root" \| "abyss-rating-input-container" \| "abyss-rating-input-sub-text" \| "abyss-rating-input-descriptors" \| "abyss-star-fill" \| "abyss-star-root" \| "abyss-star-outline" \| "abyss-star-radio-input", CSSProperties>> \| undefined		Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string \| undefined		Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean \| undefined	false	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
errorMessage	string \| undefined		Error message to display for the input. Only used when not in a FormProvider. errorMessage should not exist in useForm mode.
helper	string \| number \| bigint \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...> \| null \| undefined		Helper element next to label
hiddenFrom	Breakpoint \| undefined		When defined, the component is hidden once the screen width reaches the specified breakpoint.
hideLabel	boolean \| undefined	false	If true, hides the label visually while keeping it accessible to screen readers.
highlighted	boolean \| undefined	false	If true, the input field will be highlighted
isDisabled	boolean \| undefined	false	If true, the input will be disabled
isRequired	boolean \| undefined		Whether the input is required. Only used when not in a FormProvider. isRequired should not exist in useForm mode.
label	string		The label for the input; associated with it so screen readers announce it as the input's accessible name.
model	string \| undefined		model should not exist in useState mode. Model name for form validation. Only used when in a FormProvider.
onBlur	FocusEventHandler<HTMLInputElement> \| undefined		Callback function executed when the input is blurred
onChange	ChangeEventHandler<HTMLInputElement> \| undefined		Callback function executed when the input value changes
onFocus	FocusEventHandler<HTMLInputElement> \| undefined		Callback function executed when the input is focused
size	"sm" \| "lg" \| "$sm" \| "$lg" \| undefined	'lg'	Set the size of the radio group
slotProps	Partial<Record<string, SlotPropsValue<string>>> \| undefined		Props to pass to individual internal slots of the component, keyed by the slot name (e.g. 'button-root'). Supports className, css, style, aria-, data-, data-testid, and nested slotProps for child Abyss components. See slotProps for more information
subText	string \| { text: string; position: SubTextPosition; } \| undefined		Additional descriptive text for the input
validators	RegisterOptions \| undefined		validators should not exist in useState mode. Validators for the input. Only used when in a FormProvider.
value	string \| (readonly string[] & string) \| undefined		The value of the input. Only used when not in a FormProvider. value should not exist in useForm mode.
visibleFrom	Breakpoint \| undefined		When defined, the component is hidden until the screen width reaches the specified breakpoint.

Rating Classes

Class Name	Description
.abyss-distribution-container	Distribution row rendered for each rating distribution item
.abyss-rating-distribution-container	Distribution list container
.abyss-rating-review-action	Review count text
.abyss-rating-root	Rating root element
.abyss-rating-star	Star icon rendered for each rating position
.abyss-rating-stars-container	Container for stars
.abyss-rating-stars-wrapper	Wrapper for stars and text
.abyss-rating-text	The text/link to the right of the stars
.abyss-rating-value	The numerical value displayed next to the stars

RatingInput Classes

Class Name	Description
.abyss-rating-input-container	Star group container
.abyss-rating-input-descriptors	Descriptor element
.abyss-rating-input-label	Label element
.abyss-rating-input-root	Star group root element
.abyss-rating-input-sub-text	Subtext element
.abyss-star-fill	Filled star icon
.abyss-star-outline	Outlined star icon
.abyss-star-radio-input	Radio input for the star
.abyss-star-root	Root element for the star

A Rating is used to display some user-provided rating of an item. Rating is not a focusable component, but is accessible to screen readers. The following examples are fully accessible.

ARIA Labels

Since the visible text in a Rating is very succinct, ARIA labels are required in order to provide meaningful descriptions for assistive technologies to read to the user. For example, "3 of 5 stars," or, "Rating of 3 out of 5 stars." The ratingAriaLabel prop will override the default value, but it is important to remember that any value provided through this prop should still provide a meaningful description of the rating. In the single variant, only one star is visible, meaning that the rating number must absolutely be visible and there must be a descriptive ARIA label to relay the actual rating.

Use of the hideRating prop is possible, but discouraged. If the rating number is hidden, the rating value is only conveyed through the star icons, which may be problematic for some users. In cases where hideRating is used, it is therefore not recommended to override the ARIA label with ratingAriaLabel unless that label contains a meaningful description of the rating.

Interactive rating input

Component Tokens

Tip

Click on the token row to copy the token to your clipboard.

Rating Tokens

Search tokens

Token Name	Value
rating.color.icon.filled.rest	#D2800F
rating.color.icon.filled.hover	#D2800F
rating.color.icon.filled.active	#ad6a08
rating.color.icon.outline	#4B4D4F
rating.color.surface.progress-bar.default	#D2800F
rating.color.surface.progress-bar.endpoint	#4B4D4F
rating.color.text.label.link.disabled	#4B4D4F
rating.color.text.label.content	#4B4D4F
rating.sizing.icon.read-only.sm	16px
rating.sizing.icon.read-only.lg	24px
rating.sizing.icon.interactive.sm	24px
rating.sizing.icon.interactive.lg	40px
rating.spacing.gap.vertical.container.interactive	12px
rating.spacing.gap.vertical.container.read-only	8px
rating.spacing.gap.vertical.container.distribution	12px
rating.spacing.gap.horizontal.interactive-stars	8px
rating.spacing.gap.horizontal.container.read-only	8px
rating.spacing.gap.horizontal.container.distribution	12px

Migration Information

Read-only rating​

Rating distribution​

Size and star display​

Rating​

Reviews configuration​

Review description​

Href and onClick​

Rating ARIA label​

Heading level​

Interactive rating input​

useForm (recommended)​

useState​

Rating Props​

RatingInput Props​

Rating Classes​

RatingInput Classes​

ARIA Labels​

Interactive rating input​

Component Tokens​

Rating Tokens​

Read-only rating

Rating distribution

Size and star display

Rating

Reviews configuration

Review description

Href and onClick

Rating ARIA label

Heading level

Interactive rating input

useForm (recommended)

useState

Rating Props

RatingInput Props

Rating Classes

RatingInput Classes

ARIA Labels

Interactive rating input

Component Tokens

Rating Tokens