Text List

The Alexa text list template (AlexaTextList) displays a scrolling list of text-based list 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. You can configure the list to let users swipe items.

Import the alexa-layouts package

To use AlexaTextList, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.4.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/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	None	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	None	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	None	The background video source. Provide a source in the same format shown for the `source` property of the Video component	1.1.0
`entities`	Array	[]	Array of entity data to bind to this template.	1.2.0
`headerAttributionImage`	String	None	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	None	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	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 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`	Toggle to display the divider that appears at the bottom of header to help separate it from the content below.	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
`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
`lang`	String	""	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 about langauge-specific fonts for responsive components, see Language-specific fonts in the components and templates.	1.4.0
`layoutDirection`	String	`LTR`	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 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
`listItems`	Array of listItems		Array of text list items to present in list.	1.1.0
`onSwipeDone`	any		Command to run when the user completes the swipe action.	1.2.0
`onSwipeMove`	any		Command to run while the user swipes the item.	1.2.0
`optionsButton1Command`	any		Command to bind to the first button in the options list. Used only for TV devices.	1.2.0
`optionsButton1Text`	string		Text for the first button in the options list. Used only for TV devices.	1.2.0
`optionsButton2Command`	any		Command to bind to the second button in the options list. Used only for TV devices.	1.2.0
`optionsButton2Text`	string		Text for the second button in the options list. Used only for TV devices.	1.2.0
`primaryAction`	Command	none	The action to trigger when the user selects an item from the list.	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.	1.2.0
`swipeActionIcon`	string		The source for a custom icon to show during the swipe. When `swipeActionIconType` is `AVG`, set this property to the name of the graphic as defined in the `graphics` property or in an imported package. When `swipeActionIconType` is `image`, provide the URL of the image to display.	1.2.0
`swipeActionIconBackground`	Color		Color to use for the background color displayed behind the action icon when the user swipes the item.	1.2.0
`swipeActionIconForeground`	string		Color to use for the action icon shown when the user swipes the item.	1.2.0
`swipeActionIconType`	string		The type of graphic to use for the custom `swipeActionIcon`. Set to `AVG` or `image`. When set to `image`, provide a URL for the image in `swipeActionIcon`. When set to AVG, define an AVG in the graphics property of your document or use graphics defined in an imported package, and then set `swipeActionIcon` to the name of the graphic.	1.2.0
`swipeDirection`	string	None (no swipe gesture)	The direction of the swipe gesture to use for items in the list. Set to `backward` or `forward` to let users swipe items in the list. For backward compatibility, you can also set this property to `left` or `right`.
`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	None	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 or AlexaSwipeToAction 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 provide this array 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:

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}"
    ]
  }
}

Let users swipe the list items

To let users swipe the list items to take actions, set the swipeDirection property to one of the following values:

backward
forward
left (provided for backward compatibility)
right (provided for backward compatibility)

Then, set the other swipe-related properties as needed. These properties correspond to AlexaSwipeToAction properties:

swipeActionIcon
swipeActionIconType
swipeActionIconForeground
swipeActionIconBackground
onSwipeMove
onSwipeDone
optionsButton1Text
optionsButton1Command
optionsButton2Text
optionsButton2Command

For details about swipe actions and an example of using AlexaSwipeToAction within a text list, see AlexaSwipeToAction within an AlexaTextList.

AlexaTextList example