Display Template Reference

This reference describes specific information about display templates that you may want to include in your skill responses that create screen displays for your Alexa skill. For a reference to the Display interface directives and requests, see Display Interface Reference.

The body templates and list templates are designed to support a wide range of presentations. The following behavior applies across templates:

  • The textContent field contains primaryText, secondaryText, and tertiaryText.

  • Each list template must include at least one list item.

  • A hint can be included with BodyTemplate2, BodyTemplate6, and ListTemplate2, by use of the Hint directive. See Hint Directive.

  • For Echo Show and Fire TV Cube, the back button appears by default on each template, but can be hidden. The back button does not appear on Echo Spot, but the customer can achieve the same effect with a long swipe from the left. See Back Button Object.

The images shown below may not be to scale, and may not exactly represent what you see on the device.

When titles are displayed, they typically appear as headers, which are either left-aligned or center-aligned, depending on the template or the device.

BodyTemplate1 for simple text and image views

To use APL instead of this deprecated display template (recommended)

Create an APL document and use one of the following APL responsive templates:

  • AlexaHeadline displays brief text over a background.
  • AlexaDetail displays longer text over a background. The layout scrolls, so longer text isn't cut off.

For details, see Replace display templates with responsive templates.

BodyTemplate2 for image views and limited centered text

To use APL instead of this deprecated display template (recommended)

Create an APL document and use the AlexaDetail responsive template to display text along with a foreground image.

For details, see Replace display templates with responsive templates.

BodyTemplate3 for image views and limited left-aligned text

To use APL instead of this deprecated display template (recommended)

Create an APL document and use the AlexaDetail responsive template to display text along with a foreground image.

For details, see Replace display templates with responsive templates.

BodyTemplate6 for text and optional background image

To use APL instead of this deprecated display template (recommended)

Create an APL document and use the AlexaHeadline responsive template to display brief text over a background.

For details, see Replace display templates with responsive templates.

BodyTemplate7 for scalable foreground image with optional background image

To use APL instead of this deprecated display template (recommended)

Create an APL document and combine the following responsive components to create a similar look.

For an example, create a new APL document in the authoring tool and select the Image Display Sample.

ListTemplate1 for text lists and optional images

To use APL instead of this deprecated display template (recommended)

Create an APL document and use the AlexaTextList responsive template to display a vertical scrolling list of text items. List items can include image thumbnails and multiple fields of information.

For details, see Replace display templates with responsive templates.

ListTemplate2 for list images and optional text

To use APL instead of this deprecated display template (recommended)

Create an APL document and use the AlexaLists responsive template with listImagePrimacy set to true to display image items in a horizontal list.

For details, see Replace display templates with responsive templates.

Display template elements

This table lists all of the elements that can be found in a display template, although each template might use only a subset of these elements.

Element Description Values/Examples
typeName of the templateBodyTemplate1
BodyTemplate2
BodyTemplate3
BodyTemplate6
BodyTemplate7
ListTemplate1
ListTemplate2
tokenUsed to track selectable elements in the skill service code. The value can be any user-defined string.Dog-List-2
1212323312
backButtonUsed to place the back button on a display template.HIDDEN
VISIBLE
backgroundImageUsed to include a background image on a display template. 
{
    "contentDescription": "string",
    "sources": [
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {...}
    ]
}
titleUsed for title for a display template. The value can be any user-defined string."Doggie Carousel"
"Cake Recipes Galore"
textContentContains primaryText, secondaryText, and tertiaryText. 
{
    "primaryText": ...,
    "secondaryText": ...,
    "tertiaryText": ...
}
primaryText Contains type (which is PlainText or RichText) and text (which is a string). Limit of 8000 characters. 
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
secondaryText Contains type (which is PlainText or RichText) and text (which is a string). Limit of 8000 characters. 
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
tertiaryText Contains type (which is PlainText or RichText) and text (which is a string). Limit of 8000 characters. 
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
image References and describes the image. Multiple sources for the image can be provided. The same format is used for both `backgroundImage` and `image`. 
{
    "contentDescription": "string",
    "sources": [
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {...}
    ]
}
listItemsContains the text and images of the list items. 
  [
    {
      "token": "string",
      "image": "Image",
      "textContent": "TextContent"
    },
    ...
    ...
    {
      "token": "string",
      "image": "Image",
      "textContent": "TextContent"
    }
  ]

Other resources

For template-related information, see:

To build skills with screen display, see:

Last updated: Mar 30, 2022