ScrollToComponent Command

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

Scrolls a scrollable component forward or backward to display a specified component. The following components are scrollable:

Important: If the target component is well outside of the currently visible region, such as for a long list, this command might cause additional layout calculations. These calculations might impact performance. Whether this occurs depends on the runtime implementation of APL.

Properties

The ScrollToComponent command has the properties shown in the following table, in addition to the common command properties. Set the type property to ScrollToComponent.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property	Type	Default	Description
`align`	`first`, `center`, `last`, `visible`	`visible`	The alignment of the item after scrolling
`componentId`	Selector	`:source`	The child component to move into view.
`targetDuration`	Non-negative Integer	System default	Target duration of the scrolling animation (in milliseconds).

For example, the following command scrolls until the component with the ID recipeSteps is in view.

{
  "type": "ScrollToComponent",
  "componentId": "recipeSteps",
  "align": "center"
}

The ScrollToComponent command looks for the first Sequence or ScrollView at or before the componentId and scrolls that one.

Scrolling stops if the user touches the screen. Stopping the command stops scrolling immediately.

The ScrollToComponent command is ignored in fast mode.

align

The alignment of the item on the screen after scrolling and before speech. Alignment is an enumerated value with options shown in the following table.

Alignment	Description
`first`	The top/left side of the item is placed at the top/left side of the scrolling container.
`center`	The center of the item is placed in the center of the container.
`last`	The bottom/right side of the item is placed at the bottom/right side of the scrolling container.
`visible`	The item is moved the minimal distance necessary to bring it fully into view.

componentId

A selector that identifies the target component for the command. When not provided, defaults to :source. The :source selector targets the component that issued the ScrollToComponent command.

targetDuration

Target duration of the scrolling animation in milliseconds. The command attempts to take the specified amount of time to scroll, but might differ based on the runtime. When you don't specify the targetDuration, the command uses the runtime-defined duration. Set the targetDuration to zero to jump to the scroll position immediately.

Reinflation strategy

When the Reinflate command runs, the ScrollToComponent command can resume after Alexa reinflates the document. The command resumes when it runs on a sequencer specified in the preservedSequencers array on Reinflate. The command saves the target component and the alignment specified in the align property.

If the target component isn't in the reinflated hierarchy or isn't a descendant of a scrollable component, the command is ignored.

When Alexa reinflates the document, scrolling resumes and scrolls the target component into position as specified by align.

ScrollToComponent example

The following example shows a Sequence that displays a long list of items. The list of items includes both the color items and section headings that correspond to a range of the alphabet. Each section heading has a component ID. For example, the "N-R" section has the ID "n-r". The TouchWrapper components displayed next to the list use the ScrollToComponent to scroll to the specified section in the list.

Was this page helpful?

Provide feedback

Last updated: frontmatter-missing