Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

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

rating

hideRating

size

singleStarDisplay

ratingAriaLabel

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

Rating

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.

Notes:

• 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.

Note: 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	Required	Description
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	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	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	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[]	-	-	Optional configuration for displaying rating distribution
headingLevel	0 | 1 | 2 | 3 | 4 | 5 | 6	3	-	The heading level for the rating wrapper. When set to 0, it appears as a <span>
hideRating	boolean	false	-	Hides Rating number
hideReviews	boolean	false	-	Whether to hide the reviews section
rating	number	0	-	Rating number
ratingAriaLabel	string	-	-	Overrides the default ARIA label for Rating
reviewsConfig	ReviewsConfig	-	-	Reviews configuration object
singleStarDisplay	boolean	false	-	Whether to display a single star or 5 stars
size	"sm" | "$sm" | "lg" | "$lg"	'lg'	-	The size of Rating

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Rating.types.ts

RatingInput Props

Name	Type	Default	Required	Description
size	"sm" | "$sm" | "lg" | "$lg" | undefined	'lg'	-	Set the size of the radio group

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

RatingInput.types.ts

FormInput.types.ts

Rating Classes

Class Name	Description
.abyss-rating-root	Rating root element
.abyss-rating-stars-wrapper	Wrapper for stars and text
.abyss-rating-stars-container	Container for stars
.abyss-rating-star	Each individual star
.abyss-rating-value	The numerical value displayed next to the stars
.abyss-rating-text	The text/link to the right of the stars
.abyss-rating-review-action	Review count text
.abyss-rating-distribution-container	Distribution list container
.abyss-rating-star	Star icon wrapper
.abyss-distribution-container	Root container for distribution row
.abyss-rating-text-wrapper	Wrapper for rating text/link
.abyss-rating-link	Clickable link for star label
.abyss-rating-text	Non-clickable label for star
.abyss-distribution-progress-bar	Progress bar for distribution
.abyss-distribution-text	Percentage text

RatingInput Classes

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

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

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

Search tokens

Rating 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