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 motion component is a responsive component specifically designed to add motion to a widget. These components provide the recommended way to include motion in your widget. For example, the Motion Pager component presents content in a pager with a widget-specific page change animation. Because your widget displays in the Widget Panel alongside the other widgets the user installed, excessive motion might distract users and lead to a poor user experience.

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.

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.7.0.

Example of the imports section of a document:

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.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

Responsive components

The following table lists available responsive components in the alexa-layouts package and indicates which viewport profiles in the alexa-viewport-profiles package support the component.

Name Description Standard viewports Widget viewports

Background

Displays a video, image, or color behind your content.

Yes

Medium

Button

Displays a button the user can select with touch or a controller. You can configure the text displayed on the button, the button appearance, and the command to run when the user selects the button.

Yes

No

Card

Displays an atomic unit of content within a container. Use this component for a glanceable, digestible snapshot of information. You can configure the background, the metadata, and the command to run when the user selects the card.

Yes

No

Check Box

Displays a check box the user can toggle on and off. You can control the check box size, colors, and commands to run when the user interacts with the check box.

Yes

No

Divider

Displays a horizontal or vertical divider to create visual separation between items.

Yes

No

Footer

Displays a hint at the bottom of a screen to suggest other utterances the user might try.

Yes

No

Footer Action Button

A variant of AlexaButton for widgets. Displays a button that the user can select. You can control the button appearance and the command to run when the user selects the button.

No

Medium

Header

Displays common header information such as a title, subtitle, and back button.

Yes

Medium

Icon Button

Displays a vector graphic as a button. The user can select the button with touch or a controller. You specify the graphic to display, the button style, and the command to run when the user selects the button. AlexaIconButton automatically handles different states, such as disabled, pressed, and focused.

Yes

No

Image

Displays an image. You can display the image with standard aspect ratios (such as portrait or round) and effects such as rounded corners.

Yes

No

Image List Item

Displays an image along with text, formatted to display within a list.

Yes

No

Ordinal

Displays the number of a list item. Use this component to number list items in a component with multiple child components (such as a Sequence, Container, or Pager.

Yes

No

Page Counter

Displays a current page number and total number of pages, such as "1 | 5" for page one out of five. You can use this to number pages in a Pager.

Yes

No

Pagination Dots

Displays a graphical representation of the current page and the total number of pages in a pager. The component can animate as the user changes the pages

Yes

Medium

Photo Caption

Displays text to provide context for an image.

Yes

Medium

Progress Bar

Displays an animated progress bar to indicate ongoing activity.

Yes

Medium

Progress Bar Radial

Displays a circular progress bar on small round hubs to indicate ongoing activity.

Yes

No

Progress Dots

Displays animated dots to indicate an action is in progress.

Yes

No

Radio Button

Displays a radio button the user can toggle on and off. You can control the button size, colors, and commands to run when the user interacts with the radio button.

Yes

No

Rating

Displays a non-interactive rating for an item. You can use a default star image or provide your own custom assets for the graphic.

Yes

No

Slider

Displays an interactive progress bar. Users can drag the bar to scrub content or change settings.

Yes

No

Slider Radial

Displays a circular, interactive progress bar. Users can drag the bar to scrub content or change settings.

Yes

No

Swipe to Action

Displays an item the user can swipe to perform an action.

Yes

No

Switch

Displays a switch the user can slide between on and off. You can control the switch size, colors, and commands to run when the user interacts with the switch.

Yes

No

Text List Item

Displays text, formatted to display within a list.

Yes

Medium

Transport Controls

Displays a set of video player controls. You can customized the appearance of the buttons and define the commands to run when the user select the buttons.

Yes

Medium

For design guidance on how to use the responsive components in standard APL documents, see Alexa Design Guide: Responsive Components. For design guidance on how to use the responsive components in widgets, see Alexa Design Guide: Widget Responsive Components.

Responsive motion components

The following table summarizes the motion components in the alexa-layouts package that have been designed to work with widgets.

Name Description Standard viewports Widget viewports

Motion Pager

Displays content in a series of pages with a widget-specific "swipe away" animation for changing pages. You use APL components and responsive components or templates to define the pages to show.

No

Medium

Motion Scale

Displays content in a series of pages with a widget-specific "zoom" animation for changing pages. You use APL components and responsive components or templates to define the pages to show.

No

Medium

Press State

Creates a tap target in the body of the widget that displays a subtle animation when tapped.

No

Medium

For design guidance on how to use the responsive motion components, see Alexa Design Guide: Widget Responsive Motion Components.

Responsive templates

The following table lists available responsive templates in the alexa-layouts package and indicates which viewport profiles in the alexa-viewport-profiles package support the component.

Name Description Standard viewports Widget viewports

Detail

Displays text and an image to present information about an entity such as a person, place, or thing.

Yes

No

Grid List

Displays a list of images and text in a grid.

Yes

No

Headline

Displays short, informational text string on the screen.

Yes

No

Image Caption

Displays an image with a header and caption. You can specify the caption text as primary and secondary text, and you can specify the placement of the caption in relation to the image.

No

Medium

Image List

Displays a scrolling list of images and text.

Yes

No

Lists

Displays a list of items. You specify whether the template presents text-based list items or image-based items.

Yes

No

Paginated List

Displays a list of items in a series of pages.

Yes

No

Photo

Displays an image with a header and caption. You can specify the caption text as primary and secondary text.

No

Medium

Text List

Displays a scrolling list of text items.

Yes

Medium

Text Wrapping

Displays multiple lines of text with a header, background, and footer action button on a widget. You can display primary, secondary, and tertiary text.

No

Medium

For design guidance on how to use the responsive templates in standard APL documents, see Alexa Design Guide: Responsive Templates. For design guidance on how to use the responsive templates in widgets, see Alexa Design Guide: Widget Responsive Templates.

Right-to-left support in the components and templates

The responsive components and templates support right-to-left languages such as Arabic when used with APL 1.7 or later. For details, see Support for Right-to-left Languages.

Viewport profile support

Viewport profiles are available in the alexa-viewport-profiles package.

Standard viewport profiles include the following:

  • All hub round profiles:
    • Hub Round (@hubRoundSmall)
  • All hub landscape profiles:
    • Hub Landscape, Small (@hubLandscapeSmall)
    • Hub Landscape, Medium (@hubLandscapeMedium)
    • Hub Landscape, Large (@hubLandscapeLarge)
    • Hub Landscape, Extra Large (@hubLandscapeXLarge)
  • All hub portrait profiles:
    • Hub Portrait, Medium (@hubPortraitMedium)
  • All mobile profiles:
    • Mobile Small (@mobileSmall)
    • Mobile Medium (@mobileMedium)
    • Mobile Large (@mobileLarge)
  • All TV profiles:
  • TV Fullscreen (@tvLandscapeXLarge)

Widget viewport profiles include the following:

  • Widget Medium (@hubWidgetMedium)

For example, when you use the AlexaHeadline template, you can expect it to work well on each of the supported viewport profiles.

For details about viewport profiles, see Viewport Profiles.

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.


Was this page helpful?

Last updated: Nov 28, 2023