Rating

The Alexa rating responsive component (AlexaRating) displays a non-interactive graphic to communicate a rating for an item. You can use a default star image or provide your own custom assets for the graphic.

Compatibility

AlexaRating is designed to work with all standard viewport profiles in the alexa-viewport-profiles package:

  • All hub round profiles
  • All hub landscape profiles
  • All hub portrait profiles
  • All mobile profiles
  • All TV profiles

If you use AlexaRating on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaRating, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaRating was introduced in version 1.1.0.

AlexaRating parameters

All parameters except type are optional.

Name Type Default Description Widget support Version added

accessibilityLabel

String

"[ratingNumber] out of five stars from [ratingText]"

A string describing the rating. Voice over reads this string when the user selects the item.

Not supported

1.4.0

emptyRatingGraphic

Any

empty

The graphic to display to represent an 'empty' rating slot (such as an empty star). Used when ratingSlotMode is multiple. You can provide either a reference to an AVG or the URL of an image. When ratingGraphicType is AVG, set this property to the name of the graphic as defined in the graphics property or in an imported package. When ratingGraphicType is image, provide the URL of the image to display.

Not supported

1.1.0

entities

Array

—

Array of entity data to bind to this template.

Not supported

1.2.0

fullRatingGraphic

Any

full

The graphic to display to represent a 'full' rating slot (such as a full star). Used when ratingSlotMode is multiple. You can provide either a reference to an AVG or the URL of an image. When ratingGraphicType is AVG, set this property to the name of the graphic as defined in the graphics property or in an imported package. When ratingGraphicType is image, provide the URL of the image to display.

Not supported

1.1.0

halfRatingGraphic

Any

half

The graphic to display to represent a 'half' rating slot (such as a half star). Used when ratingSlotMode is multiple. You can provide either a reference to an AVG or the URL of an image. When ratingGraphicType is AVG, set this property to the name of the graphic as defined in the graphics property or in an imported package. When ratingGraphicType is image, provide the URL of the image to display.

Not supported

1.1.0

layoutDirection

String

${environment.layoutDirection}

Specifies the layout direction for the progress bar. Set this property to either LTR (left-to-right) or RTL (right-to-left). This property doesn't inherit the layoutDirection from the component's parent container. Therefore, explicitly set this property when needed.

For more details about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.

Not supported

1.4.0

ratingGraphicType

String

AVG

The type of graphic to use for the rating. Set to AVG or image. When set to image, provide a URL for the image to use in the relevant graphic properties. When set to AVG, define an AVG in the graphics property of your document or use graphics defined in an imported package.

Not supported

1.1.0

ratingNumber

Number

—

The numeric rating between 0 and 5. Used when ratingSlotMode is multiple.

Not supported

1.1.0

ratingSlotMode

String

multiple

Determines whether to display a single graphical asset for the rating, or build the rating from multiple image assets. When set to single, provide a single graphical asset in the singleRatingGraphic property. When multiple, provide the numeric rating in ratingNumber. With multiple, you can use a default star image or provide your own images to represent the different states for each star (full, half, or empty). See About single and multiple slot modes

Not supported

1.1.0

ratingSlotPadding

Dimension

3dp

The padding to use between each rating slot. Used when ratingSlotMode is multiple. Can be between 0dp and 4dp

Not supported

1.1.0

ratingText

String

—

The text shown besides the rating.

Not supported

1.1.0

ratingTextOpacity

Number

0.8

The opacity of the text shown next to the rating. Set to a number between 0 and 1.

Not supported

1.3.0

singleRatingGraphic

Any

—

The graphic to display to represent the rating. Used when ratingSlotMode is single. You can provide either a reference to an AVG or the URL of an image. When ratingGraphicType is AVG, set this property to the name of the graphic as defined in the graphics property or in an imported package. When ratingGraphicType is image, provide the URL of the image to display.

Not supported

1.1.0

singleRatingGraphicWidth

Dimension

—

The width of the bounding box for the single graphic that represents the rating. Used when ratingSlotMode is single.

Not supported

1.1.0

theme

String

dark

Set the dark or light color theme. The selected theme controls the colors used for the component.

Not supported

1.1.0

About single and multiple slot modes

AlexaRating has two different modes for displaying the rating, set in the ratingSlotMode property:

  • Single – Display a single, static graphic. You can provide the either an AVG or image to display and the width to use for the image.
  • Multiple – Use a numeric rating between 0 and 5, such as "3.5", to dynamically determine the set of graphics that represent the rating. This option uses three different graphics representing the state of each "slot" – full, half, or empty. For example, for a 3.5 rating, this option displays the "full" graphic three times, the "half" graphic once, and finally the "empty" graphic once. As of alexa-layouts 1.6.0 and later, the ratings round up to the nearest half-start. For example, a 3.1 rating displays three and a half stars, and a 3.6 rating displays four stars.

The AlexaRating responsive component includes default "star" graphics for the full, half, and empty states. You can use these or provide your own image or AVG.

The following example displays a 3.5 rating with the default star graphics.

{
  "type": "AlexaRating",
  "ratingSlotPadding": "4dp",
  "ratingSlotMode": "multiple",
  "ratingNumber": 3.5,
  "ratingText": "509 ratings"
}
Default star graphics for multiple slot mode
Default star graphics for multiple slot mode

The following example shows how AlexaRating rounds numbers up to the next half star. Versions of alexa-layouts before 1.6.0 didn't do this rounding.

The following example displays the single graphic defined as "customRating".


{
  "type": "AlexaRating",
  "ratingSlotMode": "single",
  "singleRatingGraphic": "customRating",
  "ratingText": "609 ratings"
}

A single graphic with green and red stars
A single graphic with green and red stars

AlexaRating example

This example shows the complete document that shows both the multiple and single rating slot examples.

Last updated: Mar 02, 2023