Rating
The rating
component provides insight regarding others’ opinions and experiences with a product. This helps other users make more-informed purchasing decisions. Users can also rate products they have purchased.
Example
Best practices
Use the rating
component to help users make informed buying decisions or to provide feedback on how they rate the product that they have purchased themselves. The data gathered by allowing users to rate products is typically used to classify products as "most popular" or "highest-rated”. That data allows users to filter on or sort by the classification or a specific rating.
Do
- Make it clear which product the rating pertains to by making sure the layout and grouping are clearly associated when several products are on the page.
- When using the
larger
rating option, it should always be used together with "Ratings & Reviews". - Use the
interactive
user-selectable rating component on product detail pages (PDPs). - Use the
read-only
rating component for product placements and a summary view of a product. - When used as a filter, make it clear to the user they are not actually rating a product or item. For example, when showing only 5 star ratings in a histogram.
- Use only whole integers or .5 decimal values ( i.e. 0, .5, 1, 1.5, 2...) for the
data-value
attribute; intermediate values cannot be recognized by CSS.
Don’t
- Do not use the rating component for data that has a continuous range, such as the brightness of a photo. Instead, use a slider.
- Do not use the interactive user-selectable rating on placement groups.
- Do not use alternative colors not specified in the style guide.
- Do not change the default number of stars (the max rating). The rating component comes with 5 stars that can be divided in half-increments, with .5 (or a half-star) being the lowest or worst rating and 5.0 being the highest or best. If your website follows this convention, it will be easier for users to interpret what the rating means.
- Do not use a single star from the rating component as a like/dislike component.
- Do not configure the rating component to have more than one
type
,rater
, orstars
class.
Accessibility
- Screen readers: All paragraph elements in the component should have
class="x-screen-reader"
set to allow access for screen readers. For components that have ratings, thex-screen-reader
paragraphs should also contain:- Rating value: This is a span with
ratingValue
itemprop containing values from 0-5 (.5 increments allowed). - Best rating: This is a span with
bestRating
itemprop containing the max value of the rating scale (typically set to the default of “5”).
- Rating value: This is a span with
- Submit buttons: Buttons require
type="submit"
so the users can submit that rating review on the star of their choice. See the interactive examples below for more information.
Options
- Read-only - The rating component is made read-only simply by excluding the form button code from the component.
- Type:
- Aggregate: This is the default setting to display aggregated ratings. Note: The
f-aggregate
class has been deprecated and is no longer required. Example use: product rating in a buy box or product placements - Individual: Use the
f-individual class
on the component root element to display star ratings made by an individual reviewer. Example use: see the ratings and reviews list of individual ratings
- Aggregate: This is the default setting to display aggregated ratings. Note: The
- Rater:
- Community: This is the default setting to display ratings averaged from the community. Note: the
f-community-rated
class has been deprecated and is no longer required. - User: Use the
f-user-rated
class on the component root element to display star ratings made by the current user.
- Community: This is the default setting to display ratings averaged from the community. Note: the
- Value: Use the
data-value
attribute on the component root element to set the number of filled stars (and half stars) to display. Valid numeric values range from 0-5 and include intervals of .5 to display half stars. - Max: Use the
data-max
attribute on the component root element to set the total max value of the scale. This value is currently set to “5”.
- Type:
- Interactive - The rating component is made interactive simply by adding the
f-interactive
class on the component root element and including the form button code in the component.- Rater:
- Community: Use the
f-community-rated
class on the component root element to display star ratings averaged from the community. - User: Use the
f-user-rated
class on the component root element to display star ratings made by the current user.
- Community: Use the
- Stars:
- Unfilled: Use the
f-none
class on the button elements for completely unfilled (unrated) stars. - Filled: Use the
f-full
class on the button elements for completely filled stars. - Half filled: Use the
f-half
class on the button elements for half-filled stars.
- Unfilled: Use the
- Rater:
Specifications
- A new shape has been introduced for the read-only version of the Rating component, effective in v1.20.0. Earlier versions are no longer recommended for use.
Development
- Schema definition: The rating schema defines the acceptable configurations, requirements, and options for each component.