Lists (1.5.0)

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

(This is not the most recent version of AlexaLists. Use the Other Versions option to see the documentation for the most recent version of AlexaLists)

The Alexa lists template (AlexaLists) displays a list of items. AlexaLists is a full-screen template that optionally displays a header, footer, and background. You specify whether the template presents text-based list items or image-based items. For text items, the template uses AlexaTextList. For image-based items, the template uses AlexaImageList on most viewports, and AlexaPaginatedList on small, round hubs.

Import the alexa-layouts package

To use AlexaLists, import the alexa-layouts package.

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

AlexaLists 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.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	—	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	—	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
`backgroundVideoAudioTrack`	String	`foreground`	Audio track to play on when playing the video. Can be `foreground` \| `background` \| `none`.	1.1.0
`backgroundVideoAutoPlay`	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
`backgroundVideoSource`	Video source	—	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. Use this 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
`emptyPrimaryText`	String	—	Primary text to display in up to two lines when the list has no items. Text is truncated to fit to two lines.	1.1.0
`emptySecondaryText`	String	—	Secondary text to display in a single line when the list has no items. Displayed below the primary text. Text is truncated to display on a single line.	1.1.0
`entities`	Array	—	Array of entity data to bind to this template.	1.2.0
`footerHintText`	String	—	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
`headerAttributionImage`	String	—	URL for attribution image source. Displays when `headerAttributionPrimacy` is `true`, or on a device that shows Title/Subtitle and Attribution.	1.1.0
`headerAttributionOpacity`	Number	`0.8`	The opacity of the attribution text and attribution image in the header. Set to a number between 0 and 1.	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.1.0
`headerAttributionText`	String	—	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	—	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 run 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	—	Secondary text to render in header.	1.1.0
`headerTitle`	String	—	Primary text to render in header.	1.1.0
`hideDivider`	Boolean	`false`	When `true`, hide the horizontal divider displayed below each item in the list. Used when `listImagePrimacy` 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
`imageHeight`	Dimension	—	Sets a default for the `imageHeight` option for the items in `listItems`. Each image in the list scales to fit within this height using the `imageScale` setting.	1.4.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 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
`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
`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.	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.	1.4.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 need to target the list for commands, such as the `SpeakList` command.	1.2.0
`listImagePrimacy`	Boolean	`false`	When `true`, the list layout adapts to promote the provided image sources as the primary wayfinding element, usually in horizontal navigation. When `false` the primary text is promoted, usually in vertical navigation. Defaults to `false`.	1.1.0
`listItems`	Array of listItems	—	Array of list items to display.	1.1.0
`primaryAction`	Command	—	Sets a default for the `primaryAction` option for the items in `listItems`. Set this to the command to trigger when the user selects an item from the list. See the `primaryAction` property in `AlexaImageListItem`.	1.1.0
`speechItems`	Any	—	An array of speech items. The `AlexaLists` 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.1.0
`touchForward`	Boolean	`false`	When `true`, assume the user is close enough to touch the screen (3ft viewing distance) and format the list items with a smaller font size. When `false`, assume the user isn't close enough to touch the screen ("voice-forward") and use a larger font size. Applies when `listImagePrimacy` is `false`.	1.1.0
`type`	String	—	Always set to `AlexaLists`.	1.1.0

Choose the list layout to display (listImagePrimacy)

The listImagePrimacy parameter determines the list layout.

When listImagePrimacy is true, the template displays either an AlexaImageList or an AlexaPaginatedList. These layouts show an image and text for each item. The AlexaPaginatedList displays on small, round hubs, so a single list item is shown on each page.

When listImagePrimacy is false, the template displays an AlexaTextList. This layout displays a scrolling list of text items.

Provide the list items

The AlexaLists template expects an array of items in the listItems property. Each item is one of the following:

An object with the same properties as those defined in the AlexaImageListItem responsive component.
An object with the same properties as those defined in the AlexaTextListItem responsive component.

The list uses the image properties when listImagePrimacy is true and ignores the image properties when listImagePrimacy is false.

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

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

Then, bind this array to the listItems property with the expression ${listData.listItemsToShow}. This example displays an AlexaImageList or AlexaPaginatedList and shows the provided images.

{
  "type": "AlexaLists",
  "listItems": "${listData.listItemsToShow}",
  "listImagePrimacy": true,
  "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
  "imageBlurredBackground": true
}

Change listImagePrimacy to false to display an AlexaTextList with the same data. This version ignores the properties that don't apply to AlexaTextList.

{
  "type": "AlexaLists",
  "listItems": "${listData.listItemsToShow}",
  "listImagePrimacy": false,
  "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
  "imageBlurredBackground": true
}

Default text for an empty list

Use the emptyPrimaryText and emptySecondaryText parameters to define text to display if there are no list items. This displays a short headline of text in the center of the screen.

The following example shows an AlexaLists with content for emptyPrimaryText and emptySecondaryText.

{
  "type": "AlexaLists",
  "listItems": "${listData.listItemsToShow}",
  "emptyPrimaryText": "${listData.emptyPrimaryText}",
  "emptySecondaryText": "${listData.emptySecondaryText}",
  "imageBlurredBackground": true
}

This example shows the data source that would produce the "empty list" message on the screen.

{
  "listData": {
    "emptyPrimaryText": "You don't have any list items",
    "emptySecondaryText": "To get started, tell me the item to add to the list",
    "listItemsToShow": []
  }
}

Set defaults for the list items

The AlexaLists template includes properties that correspond to properties in AlexaImageListItem. Use these to set default values for those properties. These apply when listImagePrimacy is true.

There are two types of defaults:

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

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

AlexaLists example

Copied to clipboard.

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

{
  "listData": {
    "headerTitle": "Alexa lists 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 lists footer hint text",
    "emptyPrimaryText": "You don't have any list items",
    "emptySecondaryText": "To get started, tell me the item to add to the list",
    "listItemsToShow": [
      {
        "primaryText": "First list item",
        "secondaryText": "Secondary text",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
        "imageProgressBarPercentage": 90,
        "imageShowProgressBar": false
      },
      {
        "primaryText": "Second list item",
        "secondaryText": "Secondary Text",
        "tertiaryText": "Tertiary text",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png",
        "providerText": "Provider Text",
        "imageProgressBarPercentage": 50
      },
      {
        "primaryText": "No image, use the default",
        "secondaryText": "Secondary text"
      },
      {
        "primaryText": "Fourth list item",
        "secondaryText": "No progress bar",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png"
      },
      {
        "primaryText": "Fifth list item",
        "secondaryText": "With background blur",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png"
      },
      {
        "primaryText": "Sixth list item (long text that wraps)",
        "secondaryText": "Longer secondary text that truncates",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/sm_blue.png"
      }
    ]
  }
}

The same AlexaLists template becomes a paginated list on a small hub

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023