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

Interactive community rating on a default theme showing 3.5 out of 5 stars

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, or stars class.

Also known as

Star rating
Rating feedback

Histogram
Ratings and reviews

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, the x-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”).
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
- 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.
- 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”.
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.
- 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.

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.

Code and preview

Read-only aggregate not rated

<div class="c-rating" data-value="0" data-max="5" itemscope itemtype="https://schema.org/AggregateRating">
    <p class="x-screen-reader">Not yet rated</p>
    <div></div>
</div>

Read-only aggregate user rated

<div class="c-rating f-user-rated" data-value="2.5" data-max="5" itemscope itemtype="https://schema.org/AggregateRating">
    <p class="x-screen-reader">User rating:
        <span itemprop="ratingValue">2.5</span>/
        <span itemprop="bestRating">5</span>
    </p>
    <div></div>
</div>

Read-only aggregate community rated

<div class="c-rating" data-value="3.5" data-max="5" itemscope itemtype="https://schema.org/AggregateRating">
    <p class="x-screen-reader">User rating:
        <span itemprop="ratingValue">3.5</span>/
        <span itemprop="bestRating">5</span>
    </p>
    <div></div>
</div>

Read-only individual not rated

<div class="c-rating f-individual" data-value="0" data-max="5" itemscope itemtype="https://schema.org/Rating">
    <p class="x-screen-reader">Not yet rated</p>
    <div></div>
</div>

Read-only individual user rated

<div class="c-rating f-user-rated f-individual" data-value="2.5" data-max="5" itemscope itemtype="https://schema.org/Rating">
    <p class="x-screen-reader">User rating:
        <span itemprop="ratingValue">2.5</span>/
        <span itemprop="bestRating">5</span>
    </p>
    <div></div>
</div>

Read-only individual community rated

<div class="c-rating f-individual" data-value="3.5" data-max="5" itemscope itemtype="https://schema.org/Rating">
    <p class="x-screen-reader">User rating:
        <span itemprop="ratingValue">3.5</span>/
        <span itemprop="bestRating">5</span>
    </p>
    <div></div>
</div>

Interactive not rated

<div class="c-rating f-interactive" itemscope itemtype="https://schema.org/Rating">
    <p class="x-screen-reader">Not yet rated</p>
    <form>
        <button class="c-glyph" type="submit" name="1" aria-label="Rate 1 star" itemprop="worstRating"></button>
        <button class="c-glyph" type="submit" name="2" aria-label="Rate 2 stars"></button>
        <button class="c-glyph" type="submit" name="3" aria-label="Rate 3 stars"></button>
        <button class="c-glyph" type="submit" name="4" aria-label="Rate 4 stars"></button>
        <button class="c-glyph" type="submit" name="5" aria-label="Rate 5 stars" itemprop="bestRating"></button>
    </form>
</div>

Interactive disabled

<div class="c-rating f-interactive" itemscope itemtype="https://schema.org/Rating">
    <p class="x-screen-reader">Not yet rated</p>
    <form>
        <button class="c-glyph" type="submit" name="1" aria-label="Rate 1 star" itemprop="worstRating" disabled="disabled"></button>
        <button class="c-glyph" type="submit" name="2" aria-label="Rate 2 stars" disabled="disabled"></button>
        <button class="c-glyph" type="submit" name="3" aria-label="Rate 3 stars" disabled="disabled"></button>
        <button class="c-glyph" type="submit" name="4" aria-label="Rate 4 stars" disabled="disabled"></button>
        <button class="c-glyph" type="submit" name="5" aria-label="Rate 5 stars" itemprop="bestRating" disabled="disabled"></button>
    </form>
</div>

Interactive user rated

<div class="c-rating f-user-rated f-interactive" itemscope itemtype="https://schema.org/Rating">
    <p class="x-screen-reader">User rating:
        <span itemprop="ratingValue">2.1</span>/
        <span itemprop="bestRating">5</span>
    </p>
    <form>
        <button class="c-glyph f-full" type="submit" name="1" aria-label="Rate 1 star" itemprop="worstRating"></button>
        <button class="c-glyph f-full" type="submit" name="2" aria-label="Rate 2 stars"></button>
        <button class="c-glyph f-half" type="submit" name="3" aria-label="Rate 3 stars"></button>
        <button class="c-glyph f-none" type="submit" name="4" aria-label="Rate 4 stars"></button>
        <button class="c-glyph f-none" type="submit" name="5" aria-label="Rate 5 stars" itemprop="bestRating"></button>
    </form>
</div>

Interactive community rated

<div class="c-rating f-community-rated f-interactive" itemscope itemtype="https://schema.org/AggregateRating">
    <p class="x-screen-reader">Community rating:
        <span itemprop="ratingValue">3.2</span>/
        <span itemprop="bestRating">5</span>
    </p>
    <form>
        <button class="c-glyph f-full" type="submit" name="1" aria-label="Rate 1 star" itemprop="worstRating"></button>
        <button class="c-glyph f-full" type="submit" name="2" aria-label="Rate 2 stars"></button>
        <button class="c-glyph f-full" type="submit" name="3" aria-label="Rate 3 stars"></button>
        <button class="c-glyph f-half" type="submit" name="4" aria-label="Rate 4 stars"></button>
        <button class="c-glyph f-none" type="submit" name="5" aria-label="Rate 5 stars" itemprop="bestRating"></button>
    </form>
</div>