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
)
- Widget Medium (
- 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 theSpeakList
command to read list items, because widgets don't support theSpeakList
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 |
---|---|---|---|---|---|
|
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 |
Medium |
1.5.0 |
|
String |
|
Image or video alignment to apply to the background image or video. |
Medium |
1.1.0 |
|
Boolean |
|
When |
Medium |
1.1.0 |
|
— |
Color to use as a background color. Used when neither |
Medium |
1.1.0 | |
|
Boolean |
|
When |
Medium |
1.1.0 |
|
String |
— |
URL for the background image source. Used when |
Medium |
1.1.0 |
|
Boolean |
|
When |
Medium |
1.1.0 |
|
String |
|
Image or video scaling to apply to background image or video. |
Medium |
1.1.0 |
|
String |
|
Audio track to play on when playing the video. Can be |
Not supported |
1.1.0 |
|
Boolean |
|
When |
Not supported |
1.1.0 |
|
— |
The background video source. Provide a source in the same format shown for the |
Not supported |
1.1.0 | |
|
String |
— |
The style of the footer action button. Set to |
Medium |
1.5.0 |
|
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 |
|
Boolean |
|
When |
Not supported |
1.7.0 |
|
Array |
— |
Array of entity data to bind to this template. |
Medium |
1.2.0 |
|
String |
— |
URL for attribution image source. Displays when |
Not supported |
1.1.0 |
|
Number |
|
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 |
|
Boolean |
|
When |
Not supported |
1.1.0 |
|
String |
— |
Attribution text to render in the header. Shown when |
Not supported |
1.1.0 |
|
Boolean |
|
When |
Not supported |
1.1.0 |
|
|
Command to run when the user selects the back button. |
Not supported |
1.1.0 | |
|
String |
|
Optional color value to use as the background color for the Header. |
Medium |
1.1.0 |
|
String |
— |
Secondary text to render in header. |
Not supported |
1.1.0 |
|
String |
— |
Primary text to render in header. |
Medium |
1.1.0 |
|
Boolean |
|
When |
Medium |
1.5.0 |
|
Boolean |
|
When |
Medium |
1.1.0 |
|
Boolean |
|
When |
Not supported |
1.1.0 |
|
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 |
Medium |
1.4.0 |
|
String |
|
Specifies the layout direction for the content. Set this property to either |
Medium |
1.4.0 |
|
String |
— |
An identifier to assign to the |
Medium |
1.2.0 |
|
Array of listItems |
— |
Array of text list items to present in list. |
Medium |
1.1.0 |
|
Array |
— |
Array of commands to run when the user reorders the list. Used when you set |
Not supported |
1.7.0 |
|
Any |
— |
Command to run when the user completes the swipe action. |
1.2.0 | |
|
Any |
— |
Command to run while the user swipes the item. |
Not supported |
1.2.0 |
|
Any |
— |
Command to bind to the first button in the options list. Used only for TV devices. |
Not supported |
1.2.0 |
|
String |
— |
Text for the first button in the options list. Used only for TV devices. |
Not supported |
1.2.0 |
|
Any |
— |
Command to bind to the second button in the options list. Used only for TV devices. |
Not supported |
1.2.0 |
|
String |
— |
Text for the second button in the options list. Used only for TV devices. |
Not supported |
1.2.0 |
|
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 |
Medium |
1.1.0 |
|
String |
The data-binding parameter name for |
Not supported |
1.7.0 | |
|
Any |
— |
An array of speech items. The template assigns each item in this array to the |
Not supported |
1.2.0 |
|
Boolean |
|
When |
Medium |
1.5.0 |
|
String |
— |
The source for a custom icon to show during the swipe. When |
Medium |
1.2.0 |
|
— |
Color to use for the background color displayed behind the action icon when the user swipes the item. |
Medium |
1.2.0 | |
|
String |
— |
Color to use for the action icon shown when the user swipes the item. |
Medium |
1.2.0 |
|
String |
— |
The type of graphic to use for the custom |
Medium |
1.2.0 |
|
String |
— |
The direction of the swipe gesture to use for items in the list. Set to |
Medium |
1.2.0 |
|
String |
|
Set the dark or light color theme. The selected theme controls the colors used for the template. |
1.1.0 | |
|
Boolean |
|
When |
Medium |
1.1.0 |
|
String |
— |
Always set to |
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 theRenderDocument
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 this method for standard viewports. In your skill code, include the array of list items in the
-
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 toARRAY
. - 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:
|
Not applicable |
Footer action button |
Not applicable |
The |
Individual list items |
|
|
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
- Define a
bind
variable with the array of list items to display. - Pass the name of the
bind
variable to thereorderListItemsDataBindingName
property. -
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 thebind
variable specified by thereorderListItemsDataBindingName
. Therefore, to send the revised list to your skill, use theSendEvent
command and pass thebind
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
. 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.
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.
Related topics
- Alexa Design System Overview
- Responsive Components and Templates
- Alexa Design Guide: Responsive Templates
Last updated: Dec 06, 2023