Image List

The Alexa image list template (AlexaImageList) displays a scrolling list of images and text. AlexaImageList is a full-screen template that optionally displays a header, footer, and background. You provide a set of image-based items to display in the list and configure the appearance of the list, such as including dividers and whether to number the items. You can also provide the command to run when a user selects an item from the list.

Import the alexa-layouts package

To use AlexaImageList, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.2.0. AlexaImageList was introduced in version 1.1.0.

AlexaImageList parameters

All parameters except type are optional.

Name Type Default Description Version added/updated

backgroundAlign

String

center

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

1.1.0

backgroundBlur

Boolean

false

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

1.1.0

backgroundColor

Color

None

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

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

1.1.0

backgroundImageSource

String

None

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

1.1.0

backgroundOverlayGradient

Boolean

false

When true, apply a gradient to the background.

1.1.0

backgroundScale

String

best-fill

Image or video scaling to apply to background image or video.

1.1.0

backgroundVideoSource

Video source

None

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

1.1.0

defaultImageSource

String

URL for a default image to use for any list items that don't have an imageSource defined. Provide a defaultImageSource to to make sure that image containers are never empty. The same defaultImageSource is used for all list items that are missing imageSource.

1.1.0

entities

Array

[]

Array of entity data to bind to this template.

1.2.0

headerAttributionImage

String

None

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

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

1.1.0

headerAttributionText

String

None

Attribution text to render in the header. Shown only when no headerAttributionImage is provided and headerAttributionPrimacy is true, or on a device that shows both Title/Subtitle and Attribution.

1.1.0

headerBackButton

Boolean

false

When true, displays a back button in the header. Set the headerBackButtonCommand property to specify a command to run when the user clicks this button.

1.1.0

headerBackButtonAccessibilityLabel

String

None

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

1.1.0

headerBackButtonCommand

Command

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

Command to execute when the user selects the back button.

1.1.0

headerBackgroundColor

String

transparent

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

1.1.0

headerDivider

Boolean

false

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

1.1.0

headerSubtitle

String

None

Secondary text to render in header.

1.1.0

headerTitle

String

None

Primary text to render in header.

1.1.0

hintText

String

None

Hint text to display in the footer. Use textToHint to add the correct wake word to the hint. Not shown on small devices unless imageMetadataPrimacy is false.

1.1.0

imageAlignment

String

center

Sets a default for the imageAlignment option for the items in listItems. See the imageAlignment property in AlexaImageListItem.

1.1.0

imageAspectRatio

String

square

Aspect ratio to use for the image bounding box for all the items in the list. Options are square, round, standard_landscape, standard_portrait, poster_landscape, poster_portrait, widescreen. This property works the same as the imageAspectRatio property for the AlexaImage responsive component except that the height and width of the bounding box are pre-defined based on the aspect ratio and can't be changed. All list items always use the same aspect ratio.

1.1.0

imageBlurredBackground

Boolean

false

Sets a default for the imageBlurredBackground option for the items in listItems. See the imageBlurredBackground property in AlexaImageListItem.

1.1.0

imageHideScrim

Boolean

false

Sets a default for the imageHideScrim option for the items in listItems. See the imageHideScrim property in AlexaImageListItem.

1.1.0

imageMetadataPrimacy

Boolean

true

When true, hide the hintText on small devices and display the secondaryText and tertiaryText. Set this property to false to hide the secondaryText and tertiaryText and display the hintText instead. This property is ignored on larger devices that have room to display both the text items and the hintText.

1.1.0

imageRoundedCorner

Boolean

true

Sets a default for the imageRoundedCorner option for the items in listItems. See the imageRoundedCorner property in AlexaImageListItem.

1.1.0

imageScale

String

best-fit

Sets a default for the imageScale option for the items in listItems. See the imageScale property in AlexaImageListItem.

1.1.0

listItems

Array of AlexaImageListItem

An array of items to display in the list. Each item is an object with the same properties as defined in AlexaImageListItem. See Provide the list items.

1.1.0

primaryAction

Command

none

Sets a default for the primaryAction option for the items in listItems. Set this property to the command to trigger when the user selects an item from the list. See the primaryAction property in AlexaImageListItem.

1.1.0

theme

String

dark

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

1.1.0

type

String

None

Always set to AlexaImageList

1.1.0

videoAudioTrack

String

foreground

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

1.1.0

videoAutoPlay

Boolean

false

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

1.1.0

Provide the list items

The AlexaImageList template expects an array of items in the listItems property. Each item is an object with the same properties as those defined in the AlexaImageListItem responsive component.

The following example illustrates an array of items in a data source called imageListData.

{
  "imageListData": {
    "listItemsToShow": [
      {
        "primaryText": "First list item",
        "secondaryText": "Secondary text",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
        "imageProgressBarPercentage": 90,
        "imageShowProgressBar": false,
        "ratingSlotMode": "multiple",
        "ratingNumber": 2.87,
        "ratingText": "(206 ratings)"
      },
      {
        "primaryText": "Second list item",
        "secondaryText": "Secondary Text",
        "tertiaryText": "Tertiary text",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png",
        "providerText": "Provider Text",
        "imageProgressBarPercentage": 50,
        "ratingSlotMode": "multiple",
        "ratingNumber": 4.5,
        "ratingText": "(500 ratings)"
      },
      {
        "primaryText": "No image, use the default",
        "secondaryText": "Secondary text",
        "ratingSlotMode": "multiple",
        "ratingNumber": 2,
        "ratingText": "(50 ratings)"
      },
      {
        "primaryText": "Fourth list item",
        "secondaryText": "No progress bar",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 5,
        "ratingText": "(452 ratings)"
      },
      {
        "primaryText": "Fifth list item",
        "secondaryText": "With background blur",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 0,
        "ratingText": "(206 ratings)"
      },
      {
        "primaryText": "Sixth list item (long text that wraps)",
        "secondaryText": "Longer secondary text that truncates",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/sm_blue.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 0,
        "ratingText": "(206 ratings)"
      }
    ]
  }
}

Then, bind this array to the listItems property with the expression ${imageListData.listItemsToShow}.

{
  "type": "AlexaImageList",
  "listItems": "${imageListData.listItemsToShow}",
  "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
  "imageBlurredBackground": true,
  "primaryAction": {
    "type": "SendEvent",
    "arguments": [
      "ListItemSelected",
      "${ordinal}"
    ]
  }
}

The specific list item parameters available depend on the version of AlexaImageListItem. For example, the properties to display a rating require the 1.2.0 or later version of the alexa-layouts package. For the full set of properties, see AlexaImageListItem.

Set defaults for the list items

The AlexaImageList template includes properties that correspond to properties in AlexaImageListItem. Use these to set default values for those properties.

There are two types of defaults:

  • Defaults you can set or override for an individual item – AlexaImageList uses the value provided on the individual item when available, and uses the value provided on AlexaImageList otherwise.

    For example, you might set imageScale to best-fit for the whole list, but then override it to best-fill for one item on the list.

  • Defaults that always apply to all the items in the list – AlexaImageList always uses the value provided on AlexaImageList for these properties. Any value in a corresponding property on an individual item is ignored.

    For example, you must set imageAspectRatio on the whole list. You can't have a list in which some items display as squares and some as circles. Any value for imageAspectRatio on a list item is ignored.

The following table lists the properties you use as defaults.

Property Can override on an item
defaultImageSource No
imageAlignment Yes
imageAspectRatio No
imageBlurredBackground Yes
imageHideScrim Yes
ImageMetadataPrimacy No
imageRoundedCorner Yes
imageScale Yes
primaryAction Yes

For details about each of these properties, see AlexaImageListItem.

Specify the action for each list item

AlexaImageList is interactive. Users can select items on the list. Set the primaryAction property to the command you want to run when the user selects an item.

When you set primaryAction on the AlexaImageList component, AlexaImageList passes the command to each item on the list.

To override command for an individual list item, set the primaryAction property on the list item itself.

The following example shows how you to use the SendEvent command to send your skill a UserEvent request. This passes the number representing the selected item as part of the SendEvent.arguments array.

{
  "primaryAction": {
    "type": "SendEvent",
    "arguments": [
      "ListItemSelected",
      "${ordinal}"
    ]
  }
}

AlexaImageList and dynamicIndexList data sources

The AlexaImageList template uses a Sequence. This means you can use a dynamicIndexList data source. With a dynamicIndexList data source, you can do the following:

  • Display large lists progressively as the user scrolls through the content (lazy loading).
  • Update the items the data source after it is already displayed, so you can change the values on the screen without sending an entirely new document.

To use a dynamicIndexList data source with AlexaImageList

  1. Follow the dynamicIndexList structure shown in dynamicIndexList data source. Don't include any other properties not defined in this structure.
  2. Put your list item objects in the items array in the data source.
  3. Bind the data source to the listItems property of AlexaImageList. This binding is equivalent to binding the data source to the data property of a Sequence in a custom layout.

The following examples show a document with an AlexaImageList that uses a dynamicIndexList data source.

For details about defining a dynamicIndexList data source, see dynamicIndexList data source.

For details about the directives and requests you use to manage the data source, see Alexa.Presentation.APL Interface Reference.

AlexaImageList example

In this example, selecting a list item sends your skill a UserEvent with "ListItemSelected" and the number of the list item.

A simple AlexaImageList
A simple AlexaImageList
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment