Grid List (1.4.0 - 1.5.0)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

The Alexa grid list template (AlexaGridList) displays a list of images and text in a grid. AlexaGridList is a full-screen template that optionally displays a header 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.

Important: AlexaGridList requires APL 1.4 or later. Provide an alternate experience for devices running older versions of APL.

Import the alexa-layouts package

To use AlexaGridList, import the alexa-layouts package.

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

AlexaGridList parameters

All parameters except type are optional.

Name	Type	Default	Description	Version added
`backgroundAlign`	String	`center`	Image/video alignment to apply to background image/video.	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`.	1.2.0
`backgroundColor`	Color	—	Color to use as a background color. Used when neither `backgroundImageSource` or `backgroundVideoSource` contain values.	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.	1.2.0
`backgroundImageSource`	String	—	URL for the background image source. Used when `backgroundVideoSource` isn't provided.	1.2.0
`backgroundOverlayGradient`	Boolean	`false`	When `true`, apply a gradient to the background.	1.2.0
`backgroundScale`	String	`best-fill`	Image or video scaling to apply to background image or video.	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.	1.2.0
`customLayoutName`	Any	—	The name of a custom layout to use for each list item. Leave this unset to use the `AlexaImageListItem` layout for your list items. See Provide the list items.	1.2.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 make sure that image containers are never empty. The same `defaultImageSource` is used for all list items that are missing `imageSource`.	1.2.0
`entities`	Array	—	Array of entity data to bind to this template.	1.2.0
`headerAttributionImage`	String	—	URL for attribution image source. Shown when `headerAttributionPrimacy` is `true`, or on a device that shows Title/Subtitle and Attribution.	1.2.0
`headerAttributionOpacity`	Number	`1` for small, round hubs. `@opacitySecondary` for all others.	The opacity of the attribution text and attribution image.	1.3.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.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.	1.2.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.2.0
`headerBackButtonAccessibilityLabel`	String	—	An accessibility label to describe the back button to customers who use a screen reader.	1.2.0
`headerBackButtonCommand`	Command	`{"type":"SendEvent","arguments":["goBack"]}`	Command to run when the user selects the back button.	1.2.0
`headerBackgroundColor`	String	`transparent`	Optional color value to use as the background color for the header.	1.2.0
`headerDivider`	Boolean	`false`	When `true`, display a divider below the header to help separate it from the content.	1.2.0
`headerSubtitle`	String	—	Secondary text to render in header.	1.2.0
`headerTitle`	String	—	Primary text to render in the header.	1.2.0
`hideOrdinal`	Boolean	`false`	When `true`, don't display the number next to each list item.	1.2.0
`imageAlignment`	String	`center`	Sets a default for the `imageAlignment` option for the items in `listItems`. See the `imageAlignment` property in `AlexaImageListItem`.	1.2.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.2.0
`imageBlurredBackground`	Boolean	`false`	Sets a default for the `imageBlurredBackground` option for the items in `listItems`. See the `imageBlurredBackground` property in `AlexaImageListItem`.	1.2.0
`imageHideScrim`	Boolean	`false`	Sets a default for the `imageHideScrim` option for the items in `listItems`. See the `imageHideScrim` property in `AlexaImageListItem`.	1.2.0
`imageMetadataPrimacy`	Boolean	`true`	When `true`, prioritize the `secondaryText` and `tertiaryText` on small devices. Set this property to `false` to hide the `secondaryText` and `tertiaryText`. This property is ignored on larger devices.	1.2.0
`imageRoundedCorner`	Boolean	`true`	Sets a default for the `imageRoundedCorner` option for the items in `listItems`. See the `imageRoundedCorner` property in `AlexaImageListItem`.	1.2.0
`imageScale`	String	`best-fit`	Sets a default for the `imageScale` option for the items in `listItems`. See the `imageScale` property in `AlexaImageListItem`.	1.2.0
`imageShadow`	Boolean	`true`	Sets a default for the `imageShadow` option for the items in `listItems`. When `true`, display a drop shadow behind the image for each list item.	1.3.0
`imageShowProgressBar`	Boolean	`true`	When `true`, display the progress bar on the image overlay. Set the progress bar percentage in each individual list item with the `imageProgressBarPercentage` property.	1.2.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.	1.4.0
`listEntities`	Any	—	Array of entity data bind to GridSequence.	1.5.0
`listId`	String	—	An identifier to assign to the `Sequence` component used for the list. Set `listId` to a value to enable voice-based scrolling with the built-in intents. Also set this parameter to an ID if you want to target the list for commands, such as the `SpeakList` command.	1.2.0
`listItemHeight`	Dimension	Calculated based on size of data to display.	The height for the list items.	1.2.0
`listItemHorizontalCount`	Number	0	The number of list items to display in a single row. Setting this property a larger value might truncate your images. Leave this unset to use a default optimized the `imageAspectRatio` and viewport size. See Horizontal list density.	1.2.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` or a set of properties defined in a custom list item. See Provide the list items.	1.2.0
`primaryAction`	Command	—	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.2.0
`speechItems`	Any	—	An array of speech items. The `AlexaGridList` template assigns each item in this array to the `speech` property of the corresponding list item. Use this property when you want to use the `SpeakList` command to speak the list items.	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the template.	1.2.0
`videoAudioTrack`	String	`foreground`	Audio track to play on when playing the video. Can be `foreground` \| `background` \| `none`.	1.2.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.2.0

Horizontal list density (`listItemHorizontalCount`)

The AlexaGridList doesn't scroll horizontally. The template displays a fixed number of items in multiple rows. You can set the number of list items to display in a single row with the listItemHorizontalCount property. By default, AlexaGridList sets listItemHorizontalCount to a number based on the imageAspectRatio and the viewport size. This default ensures that the full list items display and aren't truncated.

The following table summarizes the defaults for the standard viewport profiles and image aspect ratios.

Image aspect ratio	Hub round	Hub landscape small	Hub landscape medium	Hub landscape	TV fullscreen
Square	1	3	3	3	4
Round	1	3	3	3	4
Standard landscape	1	3	3	3	4
Standard portrait	2	4	4	4	5
Poster landscape	1	3	3	3	4
Poster portrait	2	4	4	4	5
Widescreen	1	2	2	3	4

To use these responsive defaults, leave listItemHorizontalCount not set. If you do change listItemHorizontalCount, note that AlexaGridList truncates your list items as needed to fit the specified number of items into a row.

AlexaGridList using the default density based on image aspect ratio

AlexaGridList truncates list items to fit more on the row

Provide the list items

The AlexaGridList template expects an array of items in the listItems property. Use one of the following options to structure your list items:

Provide an array of objects, each with the same properties as those defined in the AlexaImageListItem responsive component.
Define a custom layout for your list items, and then pass an array of objects that correspond to your custom items.

Use AlexaImageListItem for the list items

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

{
  "gridListData": {
    "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 ${gridListData.listItemsToShow}.

{
  "type": "AlexaGridList",
  "headerTitle": "Header Title",
  "headerAttributionImage": "https://s3.amazonaws.com/ask-skills-assets/apl-layout-assets/attribution_dark_hub_prime.png",
  "backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT6_Background.png",
  "listItems": "${gridListData.listItemsToShow}",
  "imageShowProgressBar": true
}

Use a custom layout for the list items

You can use a custom layout to define the list items displayed in AlexaGridList. Use this option when the AlexaImageListItem format doesn't meet your needs.

For more details about building your own layouts, see APL Layout.

To use a custom layout for the list items

Create an array of list items to display. Each item in the array is an object with a set of properties. The following example illustrates a list item object with two properties: listItemText and imageUrl.
```
 {
   "listItemText": "First list item",
   "imageUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png"
 }
```
In the layouts section of your APL document, create a custom layout to display a single list item. Use the data property to access the data for an individual item.

For example, if each list item in your array has an listItemText property with the list item text to display, use data.listItemText to refer to that property in the layout. AlexaGridList passes the listItems you provide to the data property for the list. For more details about how the data property works, see data array inflation.

This example illustrates a Text component within a custom layout that displays the listItemText property for an item in the data array.
```
 {
   "type": "Text",
   "height": "100dp",
   "style": "textStyleBody",
   "text": "${data.listItemText}"
 }
```

In AlexaGridList, set the customLayoutName property to the name of your custom layout and bind your array of list items to the listItems property.

     {
   "type": "AlexaGridList",
   "listItems": "${gridListData.listItemsToShow}",
   "customLayoutName": "MyListItem"
 }

The following example illustrates an AlexaGridList that uses a custom layout for the list items. The document defines a custom layout called MyListItem that displays two properties: imageUrl and listItemText. The data source example illustrates the structure of the array passed to listItems.

Note: The AlexaGridList template passes several properties to AlexaImageListItem to set defaults. For example, you can set defaultImageSource one time to specify an image to use when a given list item does not have an image. When you use a custom layout, your custom layout doesn't have access to these defaults.

Set defaults for the list items

The AlexaGridList template includes properties that correspond to properties in AlexaImageListItem. Use these to set default values for those properties. AlexaGridList ignores these defaults when you use a custom layout for your list items.

There are two types of defaults:

Defaults you can set or override for an individual item – AlexaGridList uses the value provided on the individual item when available, and uses the value provided on AlexaGridList 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 – AlexaGridList always uses the value provided on AlexaGridList 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
`imageShadow`	Yes
`primaryAction`	Yes

For details about each of these properties, see AlexaImageListItem.

Specify the action for each list item

AlexaGridList 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 AlexaGridList component, AlexaGridList 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}"
    ]
  }
}

AlexaGridList example

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

Copied to clipboard.

To learn how to test APL examples in the authoring tool, see Experiment with APL Examples in the Authoring Tool.

{
  "gridListData": {
    "headerTitle": "Alexa image list header title",
    "headerSubtitle": "Header subtitle",
    "headerAttributionImage": "https://s3.amazonaws.com/ask-skills-assets/apl-layout-assets/attribution_dark_hub_prime.png",
    "backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT6_Background.png",
    "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
    "hintText": "Alexa image list footer hint text",
    "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
      },
      {
        "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
      },
      {
        "primaryText": "No image, use the default",
        "secondaryText": "Secondary text",
        "ratingSlotMode": "multiple",
        "ratingNumber": 2
      },
      {
        "primaryText": "Fourth list item",
        "secondaryText": "No progress bar",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 5
      },
      {
        "primaryText": "Fifth list item",
        "secondaryText": "With background blur",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 0
      },
      {
        "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
      }
    ]
  }
}

AlexaGridList (partially scrolled to show the second row)

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023