Paginated List

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

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.

Compatibility

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

Import the alexa-layouts package

To use AlexaPaginatedList, import the alexa-layouts package.

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

AlexaPaginatedList parameters

All parameters except type are optional.

Name	Type	Default	Description	Widget support	Version added
`backgroundAlign`	String	`center`	Image/video alignment to apply to background image/video.	Not supported	1.1.0
`backgroundBlur`	Boolean	`false`	When `true`, display the provided background image with a blur effect. Applies when `backgroundImageSource` contains a value.	Not supported	1.1.0
`backgroundColor`	Color	—	Color to use as a background color. Used when neither `backgroundImageSource` or `backgroundVideoSource` contain values.	Not supported	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.	Not supported	1.1.0
`backgroundImageSource`	String	—	URL for the background image source. Used when `backgroundVideoSource` isn't provided. You can override this property for an individual list item by setting `imageSource` on the list item.	Not supported	1.1.0
`backgroundOverlayGradient`	Boolean	`false`	When `true`, apply a gradient to the background.	Not supported	1.1.0
`backgroundScale`	String	`best-fill`	Image or video scaling to apply to background image or video.	Not supported	1.1.0
`backgroundVideoAudioTrack`	String	`foreground`	Audio track to play on when playing the video. Can be `foreground` \| `background` \| `none`.	Not supported	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.	Not supported	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.	Not supported	1.1.0
`entities`	Array	—	Array of entity data to bind to this template.	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.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.	Not supported	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`.	Not supported	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.	Not supported	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.	Not supported	1.1.0
`headerBackButtonAccessibilityLabel`	String	`Back`	An accessibility label to describe the back button to customers who use a screen reader.	Not supported	1.1.0
`headerBackButtonCommand`	Command	`{"type":"SendEvent","arguments":["goBack"]}`	Command to run when the user selects the back button.	Not supported	1.1.0
`headerBackgroundColor`	String	`transparent`	Optional color value to use as the background color for the Header.	Not supported	1.1.0
`headerDivider`	Boolean	`false`	When `true`, display a divider below the header to help separate it from the content.	Not supported	1.1.0
`headerSubtitle`	String	—	Secondary text to render in header.	Not supported	1.1.0
`headerTitle`	String	—	Primary text to render in header.	Not supported	1.1.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
`listId`	String	—	An identifier to assign to the `Pager` 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.	Not supported	1.2.0
`listItems`	array of items	—	Array of list items to display in list.	Not supported	1.1.0
`primaryAction`	Command	—	The action to trigger when an item is selected.	Not supported	1.1.0
`speechItems`	Any	—	An array of speech items. The 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.	Not supported	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the template.	Not supported	1.1.0
`type`	String	—	Always set to `AlexaPaginatedList`.	Not supported	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 a UserEvent request with "ListItemSelected" and the number of the list item in the arguments array. To test this event, copy the example to your skill.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023