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

You can can structure and organize your content into either text, image, or paginated lists. Using the list responsive templates 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 list

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.

Image list

An example of two hub devices showing a list of 3 labeled photos of planets from NASA with a header and footer.

An image list works best when each list item corresponds to a contextually relevant image, e.g. listing out recipes with a picture of the meal itself. Image lists should be used when the items rely heavily on the image presented to help customers recognize the item quickly. For customers with low to no vision, an appropriate description of the list item should be displayed to provide context and accompany the audio. For example, the description under an image of a city should be the location, e.g. “Seattle, Washington”.

Image lists are comprised of: an ordinal denoting the position of the item in the list, the image, primary and secondary text below the image. Text should be very short at a couple words so that the focus is on the image itself.

Paginated list

Example showing the use of a page counter at the bottom of the screen with an image background on a round hub device.

The paginated list template displays a list of text items in a series of pages. This is a full-screen template that can include the header and background. The template includes a page counter that shows the current page and the total number of pages in your list.

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. Learn more about AlexaHeader.

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. Learn more about AlexaTextListItem.

Image list item

Image list items are designed to be read from top to bottom where the image is displayed first followed by a short text description. They consist of elements including the image, ordinals, primary text, and secondary text. Learn more about AlexaImageListItem.


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. Learn more about AlexaBackground.


Ordinals are used to display the number of an item in a list and are a voice indicator for similar sounding items. For example, if you have a list containing types of cookies that sound similar: chocolate chip, chocolate chunk, and double chocolate chip it's easier for your user to say "Alexa, select number one". Having the ordinal and the name of the item allows for a higher success rate. Learn more about AlexaOrdinal.

Page counter

Used only for paginated lists, this component 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. Learn more about AlexaPageCounter.

Best practices

  • Test out your list items in order by reading them aloud. This is a quick and easy way to determine if your list items are too verbose.
  • 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.
  • Have 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