Paginated List

The Alexa paginated list template (AlexaPaginatedList) displays a list of items in a series of pages. This is a full-screen template that can include the header and background. You provide a set of text-based items to display. The template includes a page counter that shows the current page and the total number of pages.

Import the alexa-layouts package

To use AlexaPaginatedList, import the alexa-layouts package.

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

AlexaPaginatedList 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, the provided background image is blurred. Applies only when backgroundImageSource is set.

1.1.0

backgroundColorOverlay

Boolean

false

When true, a scrim is applied to the background. With images and videos, this can make it easier to read the text displayed over the item.

1.1.0

backgroundColor

Color

None

Color to use as background color. Used when neither backgroundImageSource or backgroundVideoSource are provided.

1.1.0

backgroundImageSource

String

None

URL for the background image source. Used when backgroundVideoSource is not provided. You can override this property for an individual list item by setting imageSource on the list item.

1.1.0

backgroundOverlayGradient

Boolean

false

When true, a gradient is applied 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 automatically begins playing when the document is rendered on the device. Applies when backgroundVideoSource is set.

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

headerAttributionImage

String

None

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

1.1.0

headerAttributionPrimacy

Boolean

true

On devices that can only display one element due to screen size, Attribution is prioritized. Setting to false displays Title/Subtitle.

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

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

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

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

listItems

array of items

none

Array of list items to display in list.

1.1.0

primaryAction

Command

none

The action to trigger when an item is selected.

1.1.0

theme

String

dark

Colors will be switched depending on the specified theme (light/dark). Default to dark theme

1.1.0

type

String

None

Always set to AlexaPaginatedList

1.1.0

Provide the pages to display

The AlexaPaginatedList template expects an array of items in the listItems property. Each item is an object with a subset of the properties defined in the AlexaImageListItem responsive component. Not all of the properties available for an AlexaImageList are used in an AlexaPaginatedList.

The following table summarizes the AlexaImageListItem properties that AlexaPaginatedList uses. Any other properties are ignored.

Property Type Description
primaryText String Title for full-screen item.
secondaryText String Secondary text for full-screen item.
tertiaryText String Tertiary text for full-screen item.
imageSource String URL for the image to use for this item. This overrides any image provided in the backgroundImageSource for the entire list.
primaryAction Command Command to run when the user selects the item. This overrides the primaryAction set on the the full list

For example, you could define an array of items in a data source like this:

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

{
  "paginatedListData": {
    "listItemsToShow": [
      {
        "primaryText": "First list item",
        "secondaryText": "Secondary text",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
        "providerText": "This property is ignored"
      },
      {
        "primaryText": "Second list item",
        "secondaryText": "Secondary Text",
        "tertiaryText": "This one has tertiary text",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png"
      },
      {
        "primaryText": "No image, use the default",
        "secondaryText": "Secondary text"
      },
      {
        "primaryText": "Fourth list item (primary text only)",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png"
      },
      {
        "primaryText": "Fifth list item",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png"
      },
      {
        "primaryText": "Sixth list item (make this really long text that wraps on most devices. Text longer than 2 lines truncates)",
        "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 ${paginatedListData.listItemsToShow}.

{
  "type": "AlexaPaginatedList",
  "listItems": "${paginatedListData.listItemsToShow}",
  "backgroundColorOverlay": "true",
  "primaryAction": {
    "type": "SendEvent",
    "arguments": [
      "ListItemSelected",
      "${ordinal}"
    ]
  }
}

Specify the action for each list item

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

AlexaPaginatedList example

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

A simple AlexaPaginatedList
A simple AlexaPaginatedList