Motion Scale (Widget)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

The Alexa motion scale responsive component AlexaMotionScale displays content in a series of pages with a widget-specific "zoom" animation for changing pages. You use Alexa Presentation Language (APL) components and responsive components or templates to define the pages to show.

Compatibility

AlexaMotionScale is designed to work with the following widget viewport profiles in the alexa-viewport-profiles package:

Widget Medium (@hubWidgetMedium)

If you use AlexaMotionScale on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaMotionScale, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaMotionScale was introduced in version 1.5.0.

AlexaMotionScale parameters

The following table shows the AlexaMotionScale properties that work with the widget viewport profiles. Not all parameters apply to all viewport profiles. The "Widget support" column indicates the widget viewport profiles that support each parameter. For details about viewport profiles, see Viewport Profiles.

All parameters except type are optional.

Name	Type	Default	Description	Widget support	Version added
`data`	Array	—	Data to bind into the `AlexaMotionScale`. When provided, `AlexaMotionScale` uses the data array inflation method. This means that the components in `items` are inflated one time for each value in `data`.	Medium	1.5.0
`initialPage`	Integer	0	The zero-based index of the starting page to display.	Medium	1.5.0
`items`	Any	—	An array of components or a single component to display.	Medium	1.5.0
`navigation`	String	`wrap`	Specifies the allowed navigation direction. Possible values are `normal`, `none`, `wrap`, `forward-only`. These options work the same as a standard `Pager` component. For details about pager navigation options, see the `navigation` property for the `Pager` component.	Medium	1.5.0
`onPageChanged`	Array	—	Commands to run when the page changes. These commands run after the pager has fully switched to the new page.	Medium	1.5.0
`pagerId`	String	—	An identifier to use for the underlying `Pager` component within the `AlexaMotionScale` layout. Set this property to an ID if you want to target the `AlexaMotionScale` with commands, such as `AutoPage` and `SetPage`.	Medium	1.5.0
`type`	String	—	Always set to `AlexaMotionScale`.	Medium	1.5.0

Define the pages to display

Provide the pages to display in AlexaMotionScale in the items property.

AlexaMotionScale is a multi-child component. Therefore, how the items array works to define pages depends on whether you also set the data property:

When data contains an array of values, AlexaMotionScale uses the data array inflation method. This means that the components in items are inflated one time for each value in data.
When data isn't set, AlexaMotionScale uses the simple array of child components inflation method. This means that each item in the items array is inflated as a separate page.

Note: The data property doesn't have a default. If you aren't using the data property in the MotionScale, assign data to an empty array ([])

The AlexaMotionScale component doesn't display any content on its own. You must provide the components or layouts to display in the items property.

Widget-specific animation when changing pages

AlexaMotionScale uses a custom "zoom" page-change animation. When the pager changes pages, the current page scales down and fades out as the new page scales up and fades into view. The animation is the same regardless of the direction of the pager.

The following example shows this animation. The AlexaMotionScale has two pages. Each page displays an AlexaTextList with several list items. The example uses a tick event handler to change pages every three seconds.

For a widget pager with an alternative "swipe away" page transition, see Motion Pager.

AlexaMotionScale example with a background image

If you want to display content over a background image, consider whether the background should be part of the animation. For example, you could modify the previous example to set the backgroundImageSource property on the AlexaTextList template to add a background image behind the list items. However, this solution includes the background image in the zoom animation.

To keep the background image static and animate the list, place your background image outside of the AlexaMotionScale component. The following example shows a custom list with a static header and background.

AlexaMotionScale with simple array of child components inflation

The following example shows an AlexaMotionScale that uses the simple array of child components inflation method to display three pages. The pager displays each component in items as a separate page.

Was this page helpful?

Provide feedback

Last updated: Dec 06, 2023