Display Cards Overview
Display Cards for Alexa allow products to render “Now Playing” information for music, as well as static display cards for general knowledge questions, weather, to-do and shopping lists, calendar updates, and Alexa skills. If your product has a display, you can enable the Display Cards capability in the Alexa Developer Console to begin receiving directives with visual metadata. For example, after you've enabled Display Cards for your product, when a user asks, "Alexa, what is the weather?", in addition to receiving a Speak directive with Alexa TTS, you will receive a RenderTemplate directive with visual metadata that maps to design templates provided by Amazon.
- How to Enable Display Cards
- Flow and Delivery
- TemplateRuntime Directives
- Display Card Templates
- Dissecting a RenderTemplate Directive
- Rendering Instructions
- UX Considerations
- Next Steps
How to Enable Display Cards
To enable display cards, you must declare the TemplateRuntime version 1.0 interface in your call to the Capabilities API. For additional details, see Capabilities API.
Flow and Delivery
This diagram illustrates the high-level message flow for delivering visual metadata to an AVS-enabled product.

- A user asks, "Who is Usain Bolt?". Their speech is captured by your product and streamed to AVS.
- AVS returns two directives:
- A
Speak
directive that instructs your client to play Alexa TTS. - A
RenderTemplate
directive that instructs your client to display visual metadata – in this case, information about Usain Bolt.
- A
- Playback of Alexa TTS starts.
- The
RenderTemplate
directive is rendered immediately (and if possible, in tandem with theSpeak
directive) in a separate thread. - Your client informs AVS that your product has started to playback Alexa TTS by sending a
SpeechStarted
event. - When playback of Alexa TTS finishes, a
SpeechFinished
event is sent to AVS.
This is what the user will see on a tablet-sized screen:

TemplateRuntime Directives
The TemplateRuntime
interface exposes two directives for the delivery of visual metadata:
- The
RenderPlayerInfo
directive instructs your client to display visual metadata associated with user requests for audio playback (music). In addition to sendingPlay
directive, AVS will send aRenderPlayerInfo
directive with visual metadata specific to an audio content provider that your client will bind to a template and render for the end user. - The
RenderTemplate
directive instructs your client to display visual metadata associated with a user’s request for a for static display cards. For example, when a user asks “Alexa, what's the weather in San Francisco?”. In addition to sending aSpeak
directive, AVS will send aRenderTemplate
directive with visual metadata that your client will bind to a template and render for the end user.
Display Card Templates
The TemplateRuntime interface supports five templates, one for "Now Playing" and four static display cards. The visual metadata provided in each directive will map to a specific component in each display card template.
"Now Playing" visual metadata is always delivered as a RenderPlayerInfo directive and maps to the "Now Playing" template for music.
Static display cards are delivered via the RenderTemplate
directive, and always include the type parameter. This instructs your client to map the provided visual metadata to a specific template type:
Type | Description | Use Cases |
---|---|---|
BodyTemplate1 | A text only template that supports title, subtitle, text, and skill icons. | Wikipedia entries without images, and simple cards provided by Alexa Skills. |
BodyTemplate2 | A template with support for body text and a single image. | Wikipedia entries with images. |
ListTemplate1 | A template for lists and calendar entries. | Shopping lists, to do lists, and calendar entries. |
WeatherTemplate | A template designed to display weather data. | Weather |
Dissecting a RenderTemplate Directive
Let's return to our example. You'll remember that after asking Alexa, "Who is Usain Bolt?", a RenderTemplate directive was returned instructing your client to display visual metadata for the user. The directive's payload supplies important information like mainTitle, subTitle, skillIcon, textField, and image, which map directly to specific components in the display card template. In this section we're going to dissect that RenderTemplate directive.
The payload will look like this:
{ "directive": { "header": { "namespace": "TemplateRuntime", "name": "RenderTemplate", "messageId": {{STRING}}, "dialogRequestId": {{STRING}} }, "payload": { "token": "{{STRING}}", "type": "bodyTemplate2", "title": { "mainTitle": "Who is Usain Bolt?", "subTitle": "Wikipedia" }, "skillIcon": null, "textField": "Usain St Leo Bolt, OJ, CD born 21 August 1986..." "image": { "contentDescription": "{{STRING}}", "sources": [ { "url": "https://example.com/usain_bolt.jpg", "size": "LARGE" } ] } } } }
The first thing we encounter is the token
, which is used to match the Speak
directive that includes Alexa TTS, with the RenderTemplate
directive that includes visual metadata. Then there is type
. This value let's you know which display card template to choose – in this case it's bodyTemplate2
. The remaining parameters include the visual metadata that you must bind to the template. Here's a sample of the visual metadata bound to the template specification for tablet-sized screens:

Rendering Instructions
In addition to the guidance provided in the Interaction Model, these rules must be enforced by your product when rendering visual metadata:
- Read the response on the request thread and parse the directives:
- Immediately execute directives without a
dialogRequestId
on a new thread. - Immediately execute
RenderTemplate
directives on a new thread. - Place directives with a
dialogRequestId
in your queue.
- Immediately execute directives without a
- Directives in the queue should be picked up on a separate thread and handled sequentially.
Play
directives and associatedRenderPlayerInfo
directives must be in sync. UnlikeRenderTemplate
, the directive should not always be rendered immediately, but should match the sequence ofPlay
directives. For example, after sendingPlaybackNearlyFinished
, if you receive a newPlay
directive andRenderPlayerInfo
directive they must be added to the queue and handled when the currently playing track has finished. This means that your display card implementation must be aware of playback state, such as playing, stopped or paused.
UX Considerations
When implementing display cards, you need to determine how best to render visual metadata for your user. The AVS UX Design Guidelines for Display Cards provide screen specific guidance for TVs, tablets, and low resolution screens, with requirements for binding metadata, and recommendations for display card transitions, interruption behaviors, and the presentation of Alexa states.
Click here to view the AVS UX Design Overview for Display Cards.
Next Steps
- Test display cards with the [AVS Device SDK][avs-device-sdk].
- Review the directives available via the TemplateRuntime Interface.
- Make sure your product meets the functional requirements for display cards provided in our Functional Requirements for AVS.