Display Cards Overview
Display cards for Alexa allow products to render visual content, including calendars, weather, and shopping lists. If your device 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 text-to-speech (TTS), the device receives a RenderTemplate directive with visual metadata that maps to design templates provided by Amazon.
Enable display cards
To enable display cards, declare the TemplateRuntime
version 1.0 interface in your call to the Capabilities API. For more 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.
A tablet-sized screen would display something similar to the following example image:

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, such as music. In addition to sendingPlay
directive, AVS sends aRenderPlayerInfo
directive with visual metadata specific to an audio content provider that the client binds to a template and render for the user. - The
RenderTemplate
directive instructs your client to display visual metadata associated with a user 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 sends aRenderTemplate
directive with visual metadata that the client binds to a template and render for the 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 maps 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.
The RenderTemplate
directive delivers static display cards and always includes 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-based template that supports title, subtitle, text, and skill icons. | Wikipedia entries without images, and 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
For example, consider a scenario where a user asks Alexa a question, such as, "Who is Usain Bolt?" Alexa then returns a RenderTemplate
directive instructing the device to display visual metadata for the user. The directive payload supplies important information like mainTitle, subTitle, skillIcon, textField, and image, which map directly to specific components in the display card template.
The following example shows a sample payload:
{ "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 payload parameter is the token
, which corresponds to the Speak
directive that includes Alexa TTS, with the RenderTemplate
directive that includes visual metadata. Next, the type
parameter describes which display card template to choose, such as 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
Your display card implementation must be aware of playback state, such as active playback, stopped, or paused. In addition to the guidance provided in the Interaction Model, your device must enforce the following rules when rendering visual metadata:
- Read the response on the request thread and parse the directives:
- Run directives without a
dialogRequestId
on a new thread. - Run
RenderTemplate
directives on a new thread. - Place the directives with a
dialogRequestId
in your queue.
- Run directives without a
- Handle directives in the queue in a separate thread and address them sequentially.
- Sync
Play
directives with their associatedRenderPlayerInfo
directives. Use the sequence ofPlay
directives to define the queue for playback. For example, If you send aPlaybackNearlyFinished
event and then receive newPlay
andRenderPlayerInfo
directives, add these directives to the queue. Handle this pair of directives after the current track completes.
UX considerations
Determine how best to render visual metadata for your users. The AVS UX Design Guidelines for Display Cards provide screen specific guidance for TVs, tablets, and low resolution screens. The guidelines include requirements for binding metadata and recommendations for display card transitions, interruption behaviors, and the presentation of Alexa states.
For more details, see AVS UX Design Overview for Display Cards.
Next steps
- Test display cards with the AVS Device SDK.
- Review the available directives available from the TemplateRuntime Interfacereference.
- Make sure your product meets the functional requirements for display cards described by the Functional Requirements for AVS.
Last updated: Nov 27, 2023