ScrollToIndex Command

Scrolls a scrollable component forward or backward to display a particular child component, specified by the index of the child component. The following components are scrollable:

Properties

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

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, last, center, visible

visible

The alignment of the item after scrolling.

componentId

Selector

:source

The parent of the child component to move into view.

index

Integer

REQUIRED

The 0-based index of the child component to display.

targetDuration

Non-negative Integer

System default

Target duration of the scrolling animation (in milliseconds).

For example, to scroll to show the fifth step in a recipe displayed in a list, set index to 4.

  {
    "type": "ScrollToIndex",
    "componentId": "recipeSteps",
    "index": 4,
    "align": "center"
  }

The componentId doesn't have to be a Sequence, ScrollView, or GridSequence component. The ScrollToIndex command looks for the first Sequence, ScrollView, or GridSequence at or before the componentId and scrolls that one.

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

The ScrollToIndex 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 the following options.

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 to identify the parent of the target component for the command. When not provided, defaults to :source. The :source selector targets the component that issued the ScrollToIndex 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.

index

The 0-based index of the child item in the parent container to scroll into view. Negative values are measured from the end of the parent container. For example, to show the second-to-last item in a list:

  {
    "type": "ScrollToIndex",
    "index": -2,
  }

The algorithm for finding the item to display can be described loosely as follows:

  let itemIndex = index < 0 ? index + children.length : index;
  if (itemIndex >= 0 && itemIndex < children.length) {
    let child = children[itemIndex];
    scrollIntoView(child);
  }

ScrollToComponent and ScrollToIndex

In APL 2023.1 or later, you can use the ScrollToComponent command with the selector syntax instead of ScrollToIndex.

For example, the following two examples show equivalent commands. In these examples, SELECTOR contains the ID of the scrolling component, and INDEX contains the numerical index of the component to scroll into view.

{
  "type": "ScrollToIndex",
  "componentId": "SELECTOR"
  "index": INDEX
}

{
  "type": "ScrollToComponent",
  "componentId": "SELECTOR:child(INDEX)"
}

Reinflation strategy

When the Reinflate command runs, the ScrollToIndex 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 scrollable component, the target index, and the alignment.

If the scrolling component isn't contained in the reinflated hierarchy, the command is ignored.

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

ScrollToIndex example

The following example shows a Sequence that displays a long list of items. The Top and Bottom buttons run ScrollToIndex with the index property set to 0 and -1, respectively. The other three buttons calculate the index based on a percentage of items in the list and use the center option for the align property.

Was this page helpful?

Last updated: frontmatter-missing