The List template displays a set of items that the customer can browse, compare, select, or dive into.

Layouts Package

The design recommendations in the guide reference the Layouts Package, which is an additional set of properties that you will need to import to use responsive components in your skill. Check out Alexa Layouts Package for more information.

How to use the list templates

With list, you can can structure and organize your content into a text list. Using the list responsive template will ensure that your list will scale across different device modes. All lists should be enabled so that a customer can select an item in the list by voice or touch.

Text lists

Example showing the use of dividers between items in a text list on two hub devices.

A text list works well for search results (such as names and titles), contacts, and to-do lists. Each item will have an ordinal denoting the order of the items in the list to the left and the description of the list item to the right. Using a divider between each list item is a good way to keep your list content legible, especially for longer lists.

A text list item is comprised of the ordinal denoting its position in the list, primary text, secondary text, and tertiary text. It should be used when images are not available or would be distracting to the customer when picking an item. Since text lists are content heavy, use a horizontal divider between each list item to make the content easier to read.

The description for each list item should be a concise summary of the audio description of the item provided by Alexa. This also provides an easy way for the customer to select an item by voice. For example, if your skill displayed a shopping list, the primary text should say the name of the item such as “Bananas” not the description “On Sale Organic Bananas for 50 Cents” which is difficult to remember or repeat in order.

List components

The header supports navigational information for lists. List headers have 3 elements — title, attribution, and navigation — which may be hidden on smaller device modes.

Text list item

Text list items are used to display content, such as a description, for each list item. They consist of elements including ordinals, primary text, secondary text, and tertiary text.


You can optionally choose a background color or image for the response. Images will have an overlay automatically applied to help make the text readable. If you decide to use a custom background, make sure to test your list and background across different device modes to ensure your content is at a 4.5:1 contrast ratio.


Ordinals are used to display the number of an item in a list.

Page counter

Page counter displays the current page number out of a total number of pages. For example, 1 | 5 which would denote the customer is on page one out of five pages.

Best practices

  • Each item in your list should be unique, without duplicates. Your items should have concise, easy to pronounce descriptions that customers can use to select the item vocally.
  • Have Alexa read the essential content in each list item; for example, always read titles, and read secondary text only if it is critical to the voice response.
  • We recommend having Alexa read out between two and five results from your list. Adjust this number based on customer familiarity with the content, length of entity titles, how voice-friendly the titles are, and total number of elements being read.
  • All list items should give the customer the ability to choose an item by voice or by touch.

Additional resources

Back to top