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.

Compatibility

AlexaTextList is designed to work with the following viewport profiles:

  • The following widget viewport profiles in the alexa-viewport-profiles package:
    • Widget Medium (@hubWidgetMedium)
  • 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

For details about viewport profiles, see Viewport Profiles.

Differences for widgets

When you use the template within a widget, AlexaTextList displays a simplified list to accommodate the small widget size. The following list shows the template differences:

  • The background can display a color or image, but can't display video. Widgets don't support the Video component.
  • The list header displays header title text, but not attribution text, attribution images, or subtitles.
  • The list header doesn't support the back button.
  • List items display primary and secondary text and image thumbnails. List items don't display tertiary text, ratings, or item numbers.
  • You can't change the positioning of the secondary text in the list items.
  • You can't use speechItems and the SpeakList command to read list items, because widgets don't support the SpeakList command.

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

The following table shows the parameters you can set on AlexaTextList. Unless otherwise noted, standard viewport profiles support all parameters. The "Widget support" column indicates the widget viewport profiles that support each parameter. For details about viewport profiles, see Viewport Profiles.

All parameters except type are optional.

Name Type Default Description Widget support Version added

accessibilityLabel

String

—

A string describing the footer action button displayed for the list. Voice over reads this string when the user selects the button. Applies when using AlexaTextList in a widget.

Medium

1.5.0

backgroundAlign

String

center

Image or video alignment to apply to the background image or video.

Medium

1.1.0

backgroundBlur

Boolean

false

When true, display the provided background image with a blur effect. Applies when backgroundImageSource contains a value.

Medium

1.1.0

backgroundColor

Color

—

Color to use as a background color. Used when neither backgroundImageSource or backgroundVideoSource contain values.

Medium

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.

Medium

1.1.0

backgroundImageSource

String

—

URL for the background image source. Used when backgroundVideoSource isn't provided.

Medium

1.1.0

backgroundOverlayGradient

Boolean

false

When true, apply a gradient to the background.

Medium

1.1.0

backgroundScale

String

best-fill

Image or video scaling to apply to background image or video.

Medium

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

buttonStyle

String

—

The style of the footer action button. Set to contained or ingress. For details about which styles to use, see Button appearance. The theme determines the button colors. Doesn't apply when displaying the document in a non-widget viewport.

Medium

1.5.0

buttonText

String

—

Text to display on the footer action button. This text should indicate the purpose of the button. Doesn't apply when displaying the document in a non-widget viewport.

Medium

1.5.0

enableReorder

Boolean

false

When true, the user can use up and down buttons to change the order of the list items.

Not supported

1.7.0

entities

Array

—

Array of entity data to bind to this template.

Medium

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 when headerAttributionImage doesn't have a value 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, display a back button in the header.

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.

Medium

1.1.0

headerSubtitle

String

—

Secondary text to render in header.

Not supported

1.1.0

headerTitle

String

—

Primary text to render in header.

Medium

1.1.0

headerTitleCanUseTwoLines

Boolean

false

When true, long headerTitle text in a widget can wrap to two lines when needed. Applies to widget viewport profiles only. Ignored when displayed on a standard APL viewport.

Medium

1.5.0

hideDivider

Boolean

false

When true, hide the horizontal divider displayed below each item in the list.

Medium

1.1.0

hideOrdinal

Boolean

false

When true, don't display the number next to each list item.

Not supported

1.1.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.

Medium

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.

Medium

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.

Medium

1.2.0

listItems

Array of listItems

—

Array of text list items to present in list.

Medium

1.1.0

onReorder

Array

—

Array of commands to run when the user reorders the list. Used when you set reorderListItemsDataBindingName.

Not supported

1.7.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.

Not supported

1.2.0

optionsButton1Command

Any

—

Command to bind to the first button in the options list. Used only for TV devices.

Not supported

1.2.0

optionsButton1Text

String

—

Text for the first button in the options list. Used only for TV devices.

Not supported

1.2.0

optionsButton2Command

Any

—

Command to bind to the second button in the options list. Used only for TV devices.

Not supported

1.2.0

optionsButton2Text

String

—

Text for the second button in the options list. Used only for TV devices.

Not supported

1.2.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.

Medium

1.1.0

reorderListItemsDataBindingName

String

The data-binding parameter name for listItems. Required if using user-defined data binding for reorder feature.

Not supported

1.7.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

stickyButton

Boolean

false

When true, pin the footer action button to the bottom of the widget. The button overlays the text list and is always in view. When false, display the footer action button after the list items. Doesn't apply when displaying the document in a non-widget viewport.

Medium

1.5.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.

Medium

1.2.0

swipeActionIconBackground

Color

—

Color to use for the background color displayed behind the action icon when the user swipes the item.

Medium

1.2.0

swipeActionIconForeground

String

—

Color to use for the action icon shown when the user swipes the item.

Medium

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.

Medium

1.2.0

swipeDirection

String

—

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. When not set, list items don't support a swipe gesture.

Medium

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 (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.

Medium

1.1.0

type

String

—

Always set to AlexaTextList.

Medium

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. When used within a widget, the AlexaTextListItem component supports a smaller set of properties. For example, you can't display ratings or tertiary text in widget list items.

Array of list items example

The following example shows an array of list items that would work with AlexaTextList.

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

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 the following:

Bind the array of list items to the listItems property

You can bind an array of items to the listItems property in two different ways:

  • Use a data-binding expression to set listItems to an array provided in a separate data source.

    • Use this method for standard viewports. In your skill code, include the array of list items in the datasources object as part of the RenderDocument directive.
    • For a widget, you don't use RenderDocument and instead you provide the data source when you install the widget on the user's device. Therefore, use this option for data that doesn't change during the lifetime of the widget.

  • Use a data-binding expression to set listItems to an array saved in the data store on the device. Your skill can then update the contents of the data store so that the widget displays up-to-date information.

    • The data store is available to widgets. An Alexa Presentation Language (APL) document displayed in a standard viewport can't use the data store.
    • You must use the data store extension and configure the region, namespace, and key to map to an item with the dataType set to ARRAY.
    • For an example, see Example of binding an AlexaTextList to the data store for a widget.

You can also set the listItems property to a static array in the APL document. This method is useful for testing, but isn't the best practice. Use data binding to pass the array to the list when possible.

Example of binding an AlexaTextList to the data store for a widget

The following example enables the data store extension and assigns it the name DataStore. The DataStore.dataBindings property then defines a data binding named DS_ListItems that maps to the specified region, namespace, and key. The example sets the datatype for this data binding to ARRAY.

{
  "extensions": [
    {
      "uri": "alexaext:datastore:10",
      "name": "DataStore"
    }
  ],
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "TextListTestDataStore",
          "key": "mainList",
          "dataBindingName": "DS_ListItems",
          "dataType": "ARRAY"
        }
      ]
    }
  }
}

The data-binding expression ${DS_ListItems} then corresponds to the array that your skill stores in the data store. Therefore, the following instance of AlexaTextList template displays the list.

{
  "type": "AlexaTextList",
  "theme": "dark",
  "id": "myTextList",
  "backgroundColor": "red",
  "headerTitle": "Example text list in a widget",
  "buttonText": "Footer action button",
  "stickyButton": true,
  "listItems": "${DS_ListItems}"
}

You then could use the following data store commands with either the Alexa.DataStore.ExecuteCommands directive or the Data Store REST API to populate the specified area of the data store with an array of items formatted for AlexaTextList.

[
  {
    "type": "PUT_NAMESPACE",
    "namespace": "TextListTestDataStore"
  },
  {
    "type": "PUT_OBJECT",
    "namespace": "TextListTestDataStore",
    "key": "mainList",
    "content": [
      {
        "primaryText": "The first list item."
      },
      {
        "primaryText": "The second list item."
      },
      {
        "primaryText": "The third list item."
      },
      {
        "primaryText": "The fourth list item."
      }
    ]
  }
]

Specify tap actions for a text list

AlexaTextList is interactive. For a standard viewport, users can tap on the header back button and select each item on the list. For a widget, users can tap on the optional footer action button, and each individual list item. You can provide commands to run for these actions, as shown in the following table.

Tap target Configuration for a standard viewport Configuration for a widget

Header

You can configure the header back button:

  • Set headerBackButton to true.
  • Set headerBackButtonAccessibilityLabel to a string that describes the back button to users who use a screen reader.
  • Set the headerBackButtonCommand to an array of commands to run when the user taps the back button.

Not applicable

Footer action button

Not applicable
  1. Set the buttonText property to the text to display on the button.
  2. Set primaryAction to an array of commands to run when the user taps the button.

The primaryAction property also defines the default command to run for individual list items. When you use this property for the footer action button, you might want to override the default for the individual list items. Alternatively, you can write a command that performs different actions depending on the event source. For an example, see the widget example in AlexaTextList examples.

Individual list items
  • To set a default command to run for all list items, set primaryAction to an array of commands.
  • To override the default command for a list item, set primaryAction on the TextListItem object for that list item.
  • To set a default command to run for all list items, set primaryAction to an array of commands. The footer action button also uses the primaryAction command. If you are also using the footer action button, write a command that performs different actions depending on the event source. For an example, see the widget example in AlexaTextList examples.
  • To override the default command for a list item, set primaryAction on the TextListItem object for that list item.

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.

Let users change the order of the list items

You can configure the text list to let users move items up and down in the list. The reordering feature is supported for all standard viewport profiles except Hub Round Small.

To enable list reordering, set the enableReorder property to true. Each list item displays up and down arrows that the user can tap to move the item up or down. When the user taps the up or down button for an item, the AlexaTextList template updates the displayed list to show the change. By default, the template also uses SendEvent to send a request to your skill with the updated list items and runs any additional commands you provide in the onReorder property.

Use the default SendEvent command

The following example shows an AlexaTextList with enableReorder set to true. When the user taps the down arrow for the "Peonies & Petals Nursery" item, the template runs a SendEvent command to send your skill the updated list items, and also runs the SetValue command provided in the onReorder property to change the header subtitle.

The following example shows the UserEvent request sent to your skill when the user moves "Peonies & Petals Nursery" down in the list.

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2023-04-10T17:26:34Z",
  "locale": "en-US",
  "arguments": [
    {
      "primaryText": "Ivy Lane Nursery and Tree Farm"
    },
    {
      "primaryText": "Peonies & Petals Nursery",
      "ratingNumber": "3.5",
      "ratingText": "3.5"
    },
    {
      "primaryText": "House of Hyacinth"
    },
    {
      "primaryText": "Swan Nursery"
    },
    {
      "primaryText": "House of Peonies"
    },
    {
      "primaryText": "Spruce Nursery"
    }
  ],
  "components": {},
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "",
    "value": false
  },
  "token": "developer-provided-token"
}

To test the the UserEvent request in the example, copy the code to a skill.

Customize the reordering commands

If you need more control over the request sent to your skill, use the reorderListItemsDataBindingName and onReorder properties in addition to enableReorder. When the user taps a button to change the order, the AlexaTextList template updates the displayed list to show the change and runs the commands you specify in the onReorder property. The template doesn't automatically run SendEvent in this scenario. You must provide this command as part of onReorder if you want to send a request to your skill.

To customize the commands to run when the user reorders the list

  1. Define a bind variable with the array of list items to display.
  2. Pass the name of the bind variable to the reorderListItemsDataBindingName property.

  3. Set the onReorder property to the array of commands to run when the user reorders the list.

    When the user taps a button to change the list order, AlexaTextList updates the value of the bind variable specified by the reorderListItemsDataBindingName. Therefore, to send the revised list to your skill, use the SendEvent command and pass the bind variable.

The following example shows an AlexaTextList with the reorderListItemsDataBindingName property set to the bind variable dynamicListItems. The initial value for the dynamicListItems is the array of list items provided in the data source. The onReorder property passes the dynamicListItems variable to the SendEvent command to send the skill an array containing a custom object with the updated list.

The following example shows the UserEvent request sent to your skill when the user moves "Peonies & Petals Nursery" down in the list.

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2023-04-10T18:03:57Z",
  "locale": "en-US",
  "arguments": [
    {
      "revisedList": [
        {
          "primaryText": "Ivy Lane Nursery and Tree Farm"
        },
        {
          "primaryText": "Peonies & Petals Nursery",
          "ratingNumber": "3.5",
          "ratingText": "3.5"
        },
        {
          "primaryText": "House of Hyacinth"
        },
        {
          "primaryText": "Swan Nursery"
        },
        {
          "primaryText": "House of Peonies"
        },
        {
          "primaryText": "Spruce Nursery"
        }
      ],
      "type": "myCustomReorderCommand"
    }
  ],
  "components": {},
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "",
    "value": false
  },
  "token": "developer-provided-token"
}

AlexaTextList examples

The following example shows an AlexaTextList.

A simple AlexaTextList
A simple AlexaTextList

The following example shows a widget that displays a static set of items from a data source. The primaryAction property uses the Select command combined with a when statement to run a different command based on whether the user tapped the footer action button or a list item. In both cases, the event runs the SendEvent command to send a UserEvent to the skill with information about the button or item that the user tapped.

AlexaTextList in a widget
AlexaTextList in a widget

Last updated: May 15, 2023