Ratings Stars

Display a product rating.
styleKey: ratingsStars

Ratings Stars show the current rating for a product, on a scale of 1 to 5.

Usage

The rating itself can have one decimal place, e.g. a rating of 3.4.

The preview has been updated.

Reviews

You can add a reviews count and link to RatingsStars by setting the reviews and href props.

The preview has been updated.

Hide Rating

Use hideRating to conceal the numeric score (e.g. "4.5"), displaying only the visual star glyphs. Accessible text remains intact via the automatic aria-label.

The preview has been updated.

"monochromatic" skin

The "monochromatic" skin turns the stars black -- or white when using dark mode. This is intended for use only when the stars are shown on top of a light-colored background such as a hero or banner.

The preview has been updated.

Anatomy

Anatomy of the Ratings Stars

Image appears larger than the actual component.

  1. Rating star - filled
  2. Rating star - partially filled
  3. Rating star - empty

Elements

The Ratings Stars includes the following elements:

Variants

The Ratings Stars is available in the following variants:

Default variant of the Ratings Stars

Default

Use the default variant when displayed on a white/light gray background.

Monochrome variant of the Ratings Stars

Monochrome

Use the “monochromatic” variant when the stars are shown on top of a colored background such as a hero or banner.

Behaviors

States

The Ratings Stars component doesn’t have different states.

Below are examples of how the Ratings Stars appear in both light and dark mode.

Default Ratings Stars in Light Mode

Default Ratings Stars in Light Mode

Default Ratings Stars in Dark Mode

Default Ratings Stars in Dark Mode

Monochrome Ratings Stars in Light Mode

Monochrome Ratings Stars in Light Mode

Monochrome Ratings Stars in Dark Mode

Monochrome Ratings Stars in Dark Mode

Content

Recommendations

The Ratings Stars component only consists of the star icons and does not contain any text.

Best Practices

Visual illustration for the "Do" section

Do

  • Use a single star if you want to simplify the display of ratings.
  • Use the monochrome variation only when the stars are shown on top of a light-colored background such as a hero or banner.
Visual illustration for the "Don't" section

Don't

  • Use the monochrome variation when the stars are on white/light gray, such as on a PDP, a gallery page, or a gallery tile.

Props

See core props for additional props that can be applied to each of these components. Each component also accepts the React-equivalent native HTML attributes of the element it renders, unless a listed prop replaces one or a note says otherwise.
RatingsStars
Renders <div>.
proptyperequireddefaultdeprecation notes
⚠️ Deprecated
aria-label
Defines a string value that labels the current element. A localized label for describing the rating stars to assistive tech users. Should include the word "Rating", the number of filled stars, an the number of total stars. @see aria-labelledby. @example "Rating: 3.5 out of 5 stars" @deprecated This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
string
false
null
This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
ratingValue
The number of stars to be filled and the number shown, can have one decimal place
number
true
0
hideRating
Hides the numeric rating
booleannull
false
false
reviews
The amount of reviews
numbernull
false
null
href
The link to the reviews
stringnull
false
null
skin
The visual style of the Rating Stars
"standard""monochromatic"null
false
standard
⚠️ Deprecated
accessibleTextForReviewCount
A localized label for describing the review count to assistive tech users. Should include the word "Reviews" and the total number. If there are multiple reviews on a page (for example, one per product in a list of products), include a detail that distinguishes them from each other (for example, the product name). @example "100 reviews" "100 reviews, Standard Business Cards" @deprecated This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
string
false
null
This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.

Internationalization

SWAN's Internationalization System allows SWAN components to render with fully translated and accessible text out-of-the-box. The following keys are provided to allow you to override the default translation.

Default TextKey
Rating: {{rating}} out of 5 stars
ratings-stars.accessible-text
Read: {{count}} review
ratings-stars.accessible-link-text-for-review-count_one
Read: {{count}} reviews
ratings-stars.accessible-link-text-for-review-count_other
{{count}} review
ratings-stars.accessible-text-for-review-count_one
{{count}} reviews
ratings-stars.accessible-text-for-review-count_other