Responsive Components and Templates

The Alexa Design System for APL provides a set of responsive components and templates you can use in your APL document. These layouts automatically work on viewports with different modes, sizes, and shapes. Use the responsive components and templates instead of building your own layouts to create responsive APL documents with less effort.

About the responsive components and templates

In APL, a component is a primitive UI element that displays on the screen. APL defines the set of primitive components. For example, the Text component displays a block of text. When you use a component, you must build in responsiveness to different viewports yourself. For instance, for a Text component, you might create a conditional style to vary the font size or color based on viewport characteristics.

A responsive component combines components into modular, responsive elements. You can use these as building blocks in your document, similar to how you would use components. For example, Button displays a button that works on all different types of devices and handles different button states automatically.

A responsive template is a complete viewport design that combines components and responsive components. The template fills the entire viewport and includes the background, header, and content. For example, the Text List template presents a scrolling list of text items with a background and header.

Use the responsive components and templates to simplify building your APL document and make sure it works on different viewports. This is usually much simpler than building your own layouts from scratch, as illustrated here:

To create a button with a responsive component:

  1. Add AlexaButton to your document.
  2. Set the AlexaButton properties for the button text and actions to take when the user selects the button.

To create a button from scratch with components:

  1. Combine the components into a custom layout:
    • Frame
    • Text
    • TouchWrapper
  2. Set the relevant properties on each of the components.
  3. Define conditions on the components and styles to handle:
    • Different viewport sizes and shapes
    • Changing the button appearance for different buttons states (pressed, not pressed, disabled, etc.)

To create a full-screen scrolling list with a responsive template:

  1. Add AlexaTextList to your document.
  2. Set the AlexaTextList properties for the background image/color, the header text, the action to take when a user selects an item, and an array of items to display.

To create a full-screen scrolling list from scratch with components:

  1. Combine the components into a custom layout:
    • Text components to display the title at the top
    • Image component to display an icon at the top on small viewports
    • Image or Frame to create a background
    • Sequence to create a scrollable list
    • Text to show the number of each item
    • Text to show the text of each item
    • TouchWrapper to make the list items selectable
  2. Set the relevant properties on each of the components.
  3. Define conditions on the components and styles to handle different viewport sizes and shapes.

Import the alexa-layouts package

To use the responsive components and templates, add the alexa-layouts package to the import array in your document. The latest version of the alexa-layouts package is 1.2.0.

Example of the imports section of a document:

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.2.0"
    }
  ]
}

Importing alexa-layouts automatically imports alexa-styles and alexa-viewport-profiles as well. You don't need to import those packages separately.

Available responsive components and templates

See the following links for details about each available component or template.

Responsive components:

Responsive templates:

Replace display templates with responsive templates

The older Display interface worked with a set of display templates for displaying content on screens. The Display interface is deprecated. The APL responsive components and templates provide equivalents you can use to provide the same functionality.

Display template APL responsive template

BodyTemplate1

AlexaHeadline displays brief text over a background.

  • Use headerTitle for the title.
  • Use backgroundImageSource for your background image.
  • Use primaryText and secondaryText for the text content.

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

  • Use headerTitle for the title.
  • Use backgroundImageSource for your background image.
  • Use primaryText, secondaryText, and bodyText for your text content.

BodyTemplate2

AlexaDetail displays text along with a foreground image.

  • Use headerTitle for the title.
  • Use backgroundImageSource for your background image.
  • Use primaryText, secondaryText, and bodyText for your text content.
  • Use imageSource for the image.
  • Set detailImageAlignment to right to display text on the left and the image on the right.

BodyTemplate3

AlexaDetail displays text along with a foreground image.

  • Use headerTitle for the title.
  • Use backgroundImageSource for your background image.
  • Use primaryText, secondaryText, and bodyText for your text content.
  • Use imageSource for the image.
  • Set detailImageAlignment to left to display text on the right and the image on the left.

BodyTemplate6

AlexaHeadline displays brief text over a background.

  • Use headerTitle for the title.
  • Use backgroundImageSource for your background image.
  • Use primaryText and secondaryText for the text content.

BodyTemplate7

There isn't a responsive template that exactly matches BodyTemplate7. Combine multiple 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

AlexaTextList displays a vertical scrolling list of text items. List items can include image thumbnails and multiple fields of information.

ListTemplate2

AlexaLists with listImagePrimacy set to true displays image items in a horizontal list.

  • Use headerTitle for the title.
  • Use backgroundImageSource for your background image.

Images

Several display templates have an image and backgroundImage property. These properties take an image object that can specify multiple URLs for images.

In the APL responsive templates, you provide a single image URL in the relevant property:

  • backgroundImageSource for background images.
  • imageSource for a foreground image on AlexaDetail or a list item in AlexaLists.
  • imageThumbnailSource for an image in a list item in AlexaTextList

Text content

Display templates use a textContent object to provide the text to display. The textContent object has primaryText, secondaryText, and tertiaryText properties.

The APL responsive components use primaryText, secondaryText, and tertiaryText properties at the top level. Each of these properties takes a single string value with the text to display.

For example, textContent.primaryText.text property corresponds to the primaryText property in the APL template.

Note that APL doesn't have the separate PlainText and RichText text types. All APL text strings can use the markup tags described for the APL Text component. The <font>, <action>, and <img> markup tags for display templates are not supported.

List items

Display templates that display lists use a listItems array for the items. Each item in the array is an object with relevant properties such as textContent.

The APL responsive templates that display lists also use a listItems array for the items. Each item in the array is an object with properties that correspond to either AlexaTextListItem or AlexaImageListItem.

Both of these list item components have primaryText, secondaryText, and tertiaryText properties for displaying text.

The AlexaTextListItem component uses imageThumbnailSource for a thumbnail image to display next to the text. This property takes a single URL for the image.

The AlexaImageListItem component uses imageSource for the image to display for the item. This property takes a single URL for the image. You can further format the look of the images with additional "image" properties on the component.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment