Text List (1.1.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 AlexaTextList. Use the Other Versions option to see the documentation for the most recent version of AlexaTextList)

The Alexa text list template (AlexaTextList) displays a scrolling list of text items. This is a full-screen template that can include the header and background. You provide a set of text-based items to display in the list. You can configure the appearance of the list, such as including dividers and whether items should be numbered. You can also provide the command to run when a user selects an item from the list.

Import the alexa-layouts package

To use AlexaTextList, import the alexa-layouts package.

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

AlexaTextList Parameters

All parameters except type are optional.

Name	Type	Default	Description	Version added/updated
`backgroundAlign`	String	`center`	Image or video alignment to apply to the background image or 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
`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
`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 when `headerAttributionImage` doesn't have a value and `headerAttributionPrimacy` is `true`, or on a device that shows both Title/Subtitle and Attribution.	1.1.0
`headerBackButton`	Boolean	`false`	When `true`, display a back button in the header.	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
`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.	1.1.0
`hideOrdinal`	Boolean	`false`	When `true`, don't display the number next to each list item.	1.1.0
`listItems`	Array of listItems	—	Array of text list items to present in list.	1.1.0
`primaryAction`	Array of commands	—	When used with a standard viewport, defines the default action to run for the list items that don't define their own `primaryAction` commands. When used in a widget, defines the command to run when the user selects the footer action button. This command is also used as the default action for list items that don't define their own `primaryAction` commands.	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
`touchForward`	Boolean	`false`	When `true`, assume the user is close enough to touch the screen (3 foot 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.	1.1.0
`type`	String	—	Always set to `AlexaTextList`.	1.1.0

Provide the list items

The AlexaTextList layout expects an array of items in the listItems property. Each item is an object with the properties defined in the AlexaTextListItem responsive component.

For example, you could define an array of items like this:

{
  "listItems": [
    {
      "primaryText": "First item primary text",
      "secondaryText": "This is the secondary text",
      "secondaryTextPosition": "bottom",
      "tertiaryText": "This is the tertiary text",
      "tertiaryTextPosition": "bottom",
      "ratingNumber": 2,
      "imageThumbnailSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_brie.png",
      "hideOrdinal": true,
      "touchForward": true
    },
    {
      "primaryText": "Second item in the list.",
      "secondaryText": "Secondary text for the second item",
      "imageThumbnailSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
      "tertiaryText": "Tertiary text",
      "tertiaryTextPosition": "bottom",
      "ratingNumber": 0
    },
    {
      "primaryText": "Third item in the list.",
      "imageThumbnailSource": "https://d2o906d8ln7ui1.cloudfront.net/images/sm_blue.png"
    },
    {
      "primaryText": "Fourth item in the list"
    },
    {
      "primaryText": "Fifth item in the list"
    },
    {
      "primaryText": "This list might have many more items"
    }
  ]
}

You can define this in the listItems array parameter of AlexaTextList, or in a separate data source.

The specific list item parameters available depends on the version of AlexaTextListItem. 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 AlexaTextListItem.

Specify the action for each list item

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

AlexaTextList example

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023