Detail


The Alexa detail template (AlexaDetail) displays text and an image to present information about an entity such as a person, place, or thing. AlexaDetail includes four variants: Generic, Movies and TV, Location, and Recipe. Use AlexaDetail for long-form structured content with a short voice synopsis.

This is a full-screen template that can include a header, footer, and background.

Compatibility

AlexaDetail 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 AlexaDetail on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaDetail, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaDetail was introduced in version 1.2.0.

AlexaDetail parameters

All parameters except type are optional. AlexaDetail has multiple different layouts for different types of content. Not all properties apply to all of the different layouts. For more information about the different layouts, see AlexaDetail content types and layouts.

Name Type Default Description Widget support Version added

backgroundAlign

String

center

Image/video alignment to apply to background image/video. Defaults to center.

Not supported

1.2.0

backgroundBlur

Boolean

false

When true, display the provided background image with a blur effect. Applies when backgroundImageSource contains a value. Defaults to false.

Not supported

1.2.0

backgroundColor

Color

Color to use as a background color. Used when neither backgroundImageSource or backgroundVideoSource contain values.

Not supported

1.2.0

backgroundColorOverlay

Boolean

false

When true, apply a scrim to the background to make it easier to read the text displayed over the image or video.

Not supported

1.2.0

backgroundImageSource

String

URL for the background image source. Used when backgroundVideoSource isn't provided.

Not supported

1.2.0

backgroundOverlayGradient

Boolean

false

When true, apply a gradient to the background.

Not supported

1.2.0

backgroundOverlayNoise

Boolean

false

When true, the Noise filter is applied to the background image.

Not supported

1.2.0

backgroundScale

String

best-fill

Image or video scaling to apply to background image or video. Defaults to best-fill.

Not supported

1.2.0

backgroundVideoAudioTrack

String

foreground

Audio track to play on when playing the video. Can be foreground | background | none Defaults to foreground.

Not supported

1.2.0

backgroundVideoAutoPlay

Boolean

false

When true, the video begins playing automatically when the document renders on the device. Applies when backgroundVideoSource contains a value. Defaults to false.

Not supported

1.2.0

backgroundVideoSource

Video source

The background video source. Provide a source in the same format shown for the source property of the Video component.

Not supported

1.2.0

bodyText

String

The main body text to display. Since the entire layout scrolls, the body text can be long. This property is ignored when detailType is recipe.

Not supported

1.2.0

button1AccessibilityLabel

String

button1Text

A string describing button 1. Voice over reads this string when the user selects the button.

Not supported

1.2.0

button1PrimaryAction

Command

The action to trigger when the user selects button 1.

Not supported

1.2.0

button1Style

String

contained

The style to use for button 1. Set to contained or outlined. For details about the options, see the buttonStyle property for AlexaButton.

Not supported

1.2.0

button1Text

String

The text to display on button 1. Button text should indicate the purpose of the button. Leave this property not set to remove button 1 from the layout. When both button1Text and button2Text are omitted, the entire button row is removed.

Not supported

1.2.0

button1Theme

String

dark

Color theme to use for button 1. Set to light or dark.

Not supported

1.2.0

button2AccessibilityLabel

String

button2Text

A string describing button 2. Voice over reads this string when the user selects the button.

Not supported

1.2.0

button2PrimaryAction

Command

The action to trigger when the user selects button 2.

Not supported

1.2.0

button2Style

String

contained

The style to use for button 2. Set to contained or outlined. For details about the options, see the buttonStyle property for AlexaButton.

Not supported

1.2.0

button2Text

String

The text to display on button 2. Button text should indicate the purpose of the button. Leave this property not set to remove button 2 from the layout. When both button1Text and button2Text are omitted, the entire button row is removed.

Not supported

1.2.0

button2Theme

String

dark

Color theme to use for button 2. Set to light or dark.

Not supported

1.2.0

detailImageAlignment

String

left

Determines the placement of the image on viewports wide enough to show the image and content side-by-side. Set to start or end. AlexaDetail positions the image based on the value in layoutDirection. For backward compatibility, you can also set this property to left or right. .

Not supported

1.2.0

detailType

String

generic

Specifies the type of layout to display. Set to one of the following: generic, moviesTV, location, or recipe. For details about each type of layout, see AlexaDetail content types and layouts.

Not supported

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

entities

Array

Array of entity data to bind to this template.

Not supported

1.2.0

externalLinkButtonAccessibilityLabel

String

externalLinkButtonText

Voice over will read this string when the user selects external link button.

Not supported

1.6.0

externalLinkButtonPrimaryAction

Command

The action to trigger when the user selects the external link button.

Not supported

1.6.0

externalLinkButtonText

String

The text shown on external link button of the content block.

Not supported

1.6.0

externalLinkButtonTheme

String

Color theme to use for the external link button. Set to light or dark.

Not supported

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

headerAttributionImage

String

URL for attribution image source. Displays when headerAttributionPrimacy is true, or on a device that shows Title/Subtitle and Attribution.

Not supported

1.2.0

headerAttributionPrimacy

Boolean

true

When true, display the headerAttributionImage on devices that display a single element due to screen size. When false, display the headerTitle and headerSubtitle.

Not supported

1.2.0

headerAttributionText

String

Attribution text to render in the header. Shown when headerAttributionImage doesn't have a value and headerAttributionPrimacy is true, or on a device that shows both Title/Subtitle and Attribution.

Not supported

1.2.0

headerBackButton

Boolean

false

When true, display a back button in the header.

Not supported

1.2.0

headerBackButtonAccessibilityLabel

String

Back

An accessibility label to describe the back button to customers who use a screen reader.

Not supported

1.2.0

headerBackButtonCommand

Command

{"type":"SendEvent","arguments":["goBack"]}

Command to run when the user selects the back button.

Not supported

1.2.0

headerBackgroundColor

String

transparent

Optional color value to use as the background color for the header.

Not supported

1.2.0

headerDivider

Boolean

false

When true, display a divider below the header to help separate it from content.

Not supported

1.2.0

headerSubtitle

String

Secondary text to render in header.

Not supported

1.2.0

headerTitle

String

Primary text to render in header.

Not supported

1.2.0

imageAccessibilityLabel

String

A string describing the image. Voice over reads this string when the user selects this component.

Not supported

1.7.0

imageAlignment

String

center

Determines how to position the image within the bounding box. Used when the image is smaller than the bounding box. Options are bottom, bottom-left, bottom-right, center, left, right, top, top-left, top-right. For more details about image alignment, see the imageAlignment property on AlexaImage.

Not supported

1.2.0

imageAspectRatio

String

square

Aspect ratio to use for the image bounding box. The image width is set to a standard default based on the aspect ratio. Options are square, round, standard_landscape, standard_portrait, poster_landscape, poster_portrait, and widescreen.

For more details about aspect ratios, see the imageAspectRatio property on AlexaImage. However, note that within AlexaDetail, you cannot specify the width of the image. To calculate the image size based on the aspect ratio, leave imageHeight not set.

Not supported

1.2.0

imageBlurredBackground

Boolean

false

When true, display a blurred version of the image behind the image. size. Ignored when imageScale is set to fill or best-fill. For more details about this property, see the imageBlurredBackground property on AlexaImage.

Not supported

1.2.0

imageCaption

String

A title or brief explanation of the image, displayed below the image.

Not supported

1.2.0

imageHeight

Dimension

Height of the image bounding box. The image is scaled to fit within this height using the imageScale setting.

When imageHeight isn't set, the bounding box for the image uses a default width and calculates the height based on the selected imageAspectRatio.

When imageHeight is set, the bounding box for the image uses the specified height and a default width based on the selected imageAspectRatio. The resulting image then might not match the specified imageAspectRatio. For best results, set imageAspectRatio to the shape you want and leave imageHeight not set.

Not supported

1.2.0

imageRoundedCorner

Boolean

true

When true, use rounded corners for the image.

Not supported

1.2.0

imageScale

String

best-fit

Determines how to scale the image to fit within the bounding box. Options are none, fill, best-fit, best-fill, or best-fit-down. For more details about image scaling, see the imageScale property on AlexaImage.

Not supported

1.2.0

imageShadow

Boolean

true

When true, display a drop shadow behind the image.

Not supported

1.3.0

imageSource

String

URI for the image to display.

Not supported

1.2.0

ingredientListItems

Any

Applies when detailType is recipe. Array of objects representing the recipe ingredients to display in a list. Each object has two properties:

ingredientsContentText – Contains the text to display.
ingredientsPrimaryAction – The command to run when the user selects the ingredient item.

See Recipe.

Not supported

1.2.0

ingredientsHideDivider

Boolean

false

When true, hide the divider between each ingredient item.

Not supported

1.2.0

ingredientsText

String

Applies when detailType is recipe. A heading to display before the list of ingredients. See Recipe.

Not supported

1.2.0

lang

String

${environment.lang}

The language for the text displayed in the template. This language determines the default font used for the text. For example, when set to ar-SA, the component uses Arabic fonts when available on the device. Set to a BCP-47 string.

For more details about language-specific fonts for responsive components, see Language-specific fonts in the components and templates.

Not supported

1.4.0

layoutDirection

String

${environment.layoutDirection}

Specifies the layout direction for the content. 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

locationText

String

Applies when detailType is location. Text to display after the primaryText to display the location name or address. See Location.

Not supported

1.2.0

primaryText

String

The primary text to display in the content area. The primaryText displays in a larger font to provide a title.

Not supported

1.2.0

quaternaryText

String

Applies when detailType is moviesTV. A fourth block of text to display in the content block. Useful for displaying movie or show length or other details about the item. See Movies and TV.

Not supported

1.2.0

ratingGraphicType

String

AVG

The type of graphic to use for the rating. Set to AVG or image.

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

ratingNumber

Number

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

ratingSlotPadding

Dimension

3dp

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

ratingText

String

Text to display next to the rating.

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

scrollViewId

String

The component ID for the ScrollView used to present the content. Set this property when you need to target the component with commands.

Not supported

1.2.0

secondaryText

String

The secondary text to display in the content area, after the primaryText.

Not supported

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

singleRatingGraphicWidth

Dimension

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

Used with the variants that display a rating (moviesTV, location, and recipe). For details about how to use the AlexaRating properties, see AlexaRating.

Not supported

1.2.0

tertiaryText

String

Applies when detailType is moviesTV. A third block of text to display in the content block. Useful for displaying movie or show length or other details about the item. See Movies and TV.

Not supported

1.2.0

theme

String

dark

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

Not supported

1.2.0

type

String

Always set to AlexaDetail.

Not supported

1.2.0

AlexaDetail content types and layouts

AlexaDetail includes four different layouts for displaying different types of content. The overall layout with an image on one side and text content on the other is the same across these variants.

You set the variant you want with the detailType parameter.

Generic

The generic (generic) layout is the default. This variant displays an image on one side of the viewport and a content section with text on the other side. You can also choose to include up to two buttons.

AlexaDetail: Generic variant
AlexaDetail: Generic variant

Movies and TV

The movies and TV variant (moviesTV) follows the same layout as generic and adds the following properties:

  • tertiaryText / quaternaryText – These properties define text to display below the standard secondaryText and are useful for information such as the show length and genre.
  • rating* – The rating properties let you display either a calculated star rating, or a custom rating in the form of a graphic. When included, the rating displays on the same line as the tertiaryText. For details about how the rating properties work, see AlexaRating.

The following example illustrates the properties specific to moviesTV:

  • The tertiaryText property contains the duration of the show.
  • The quaternaryText property is set.
  • The rating properties are set to display a custom "PG" rating graphic.

AlexaDetail: movies and TV variant
AlexaDetail: movies and TV variant

Location

The location variant (location) follows the same layout as generic, and adds the following properties:

  • locationText – Defines text to display the location. Use this to display the name or address of the location. When included, the location displays after the primaryText and the rating, before the secondaryText.
  • rating* – The rating properties let you display either a calculated star rating, or a custom rating in the form of a graphic. When included, the rating displays immediately after the primaryText. For details about how the rating properties work, see AlexaRating.

The following example illustrates the properties specific to location:

  • The locationText property contains a line of text.
  • The rating properties are configured to display a star rating set by providing a number in the ratingNumber property.

This example also illustrates how the entire button row disappears when you leave both button1Text and button2Text not set.

AlexaDetail: location variant
AlexaDetail: location variant

Recipe

The recipe variant (recipe) follows the same layout as generic and adds the following properties:

  • rating* – The rating properties let you display either a calculated star rating, or a custom rating in the form of a graphic. When included, the rating displays immediately after the primaryText. For details about how the rating properties work, see AlexaRating.
  • ingredientsText – A heading to display before the list of ingredients.
  • ingredientsHideDivider – When true, hide the divider line between each ingredient in the ingredients list.
  • ingredientListItems – An array of items to display as a list of ingredients. Each item has ingredientsContentText and ingredientsPrimaryAction properties.

The recipe variant doesn't use the bodyText property.

The following example illustrates the properties specific to recipe:

  • The ingredientsText, ingredientsHideDivider, and ingredientListItems properties are all set.
  • The rating properties are configured to display a star rating set by providing a number in the ratingNumber property.

AlexaDetail: recipe variant
AlexaDetail: recipe variant

AlexaDetail example

The following example illustrates a complete document and data source that uses AlexaDetail. This example uses the generic variation.



Was this page helpful?

Last updated: Nov 28, 2023