Sequence uses a data set to inflate a repeating set of components and display them in a long scrolling list.
Sequence is similar to a Container, the
Sequence has better performance for long lists of items. The
Sequence has a less-flexible layout model.
You can also use a
Sequence to allow ordinal and anaphor-based selection of items on the screen. For details, see APL Support for Item Selection.
The Sequence component has the following properties:
- All actionable component properties
- All multi-child component properties
- All base component properties
Sequenceproperties listed in following table. See the meaning of the columns.
Array of commands
Commands to run during scrolling.
Array of string
Properties to save when reinflating the document with the
The direction to scroll this
The alignment that the child components snap to when scrolling stops.
height and width
To minimize visibility errors, the height of a vertical sequence and the width of a horizontal sequence initialize to 100 dp when not specified. Don't use
auto for the
width. Use an absolute or relative dimension for the
Any item template inside a vertical
Sequence that has a height value must use absolute dimensions and can't use a percentage value for the height. Any item template inside a horizontal
Sequence that has a width value must use absolute dimensions and can't use a percentage value for the width.
layoutDirection component property
layoutDirection property determines the direction to display the items when the
scrollDirection property is
- Left-to-right (LTR) – The
Sequencearranges items starting on the left side. Items scroll into view from the right.
- Right-to-left (RTL) – The
Sequencearranges items starting from the right side. Items scroll into view from the left.
true, set the data-binding ordinal for each of the items in the sequence. The ordinals start with "1" and increment by one unless the
numbering property in the child component is
lastItem aren't included in ordinal numbering.
numbered property doesn't display any numbers on the screen automatically. You can use the
ordinal value in the data-binding context to display the numbers in a
Commands to run during scrolling. The runtime attempts to run these commands one time per drawing frame during scrolling, but this attempt might not succeed. On slow hardware, the
onScroll command might run intermittently.
event.source.position reported in the command is the percentage of the current scroll position as expressed by the width or height of the sequence. For example, assume the
Sequence is 200 pixels wide and the contents have scrolled left by 520 pixels. The
event.source.position value is 2.60.
The event generated has the following form.
... // Component source properties
Refer to Event source for a description of
onScroll event handler runs in fast mode.
An array of dynamic component properties and bound properties to save when reinflating the document with the
Sequence has the following component-specific property names you can assign to the
centerId– The id of the child in the center of the sequence.
centerIndex– The index of the child in the center of the sequence
firstId– The id of the child at the top of the sequence.
firstIndex– The index of the child at the top of the sequence.
scrollOffset– Absolute scroll position (measured in dp).
scrollPercent– Relative scroll position (measured as percentage of the visible area).
firstIndex option uses the index of the current child shown at the start of the sequence and (after reinflation) sets the scroll position to place the same child (by index) at the start of the sequence. The
firstId uses the
id of the current child shown at the start of the sequence and (after reinflation) sets the scroll position to put the same child (by
id) at the start of the sequence.
centerIndex option uses the index of the current child shown in the center of the sequence and (after reinflation) sets the scroll position to place the same child (by index) in the center of the sequence. The
centerId uses the
id of the current child shown in the center of the sequence and (after reinflation) sets the scroll position to put the same child (by
id) in the center of the sequence.
When searching by
id (for both
firstId), if the
id is not found either before reinflation or after reinflation, the sequence is positioned at the start. When searching for a component by
index (for both
firstIndex), if no child is present at that index, the sequence is positioned at the start.
The direction to lay out and scroll the
Sequence items. The
scrollDirection property can be one of the following:
vertical– Display the items in a vertical list. The list scrolls up and down.
horizontal– Display the items in a horizontal list. The list scrolls left and right.
The alignment that the child components snap to when scrolling stops. When the user scrolls through the content and then stops scrolling, the
Sequence can shift the child items to "snap" to the start, center, or end of the
Sequence container. The
Sequence aligns the child item closest to the snap position. For example, when
Sequence shifts the items so that the item closest to the center snaps to the center of the container.
Sequence supports two types of snap behavior:
- Snap when scrolling has velocity – When the user scrolls through the content, releases the pointer, and allows the sequence to slow to a stop, the
Sequencealigns the child components as requested or at the start or end of the sequence. No snapping occurs when the user releases the pointer with little or no scroll velocity. For this type of snapping, set
- Always snap (force snap) – After the user releases the pointer, the
Sequencealways aligns the child components as requested or at the start or end of the
Sequence. With the force snap behavior, the scroll velocity doesn't matter. For this type of snapping, set
Snapping excludes any
padding when determining the start, center, or end of the
snap property can take the following values:
none– (Default) No snapping occurs.
start– Align the starting side of the child component to the start of the container when scrolling has velocity.
center– Align the center of the child component to the center of the container when scrolling has velocity.
end– Align the ending side of the child component to the end of the container when scrolling has velocity.
forceStart– Align the starting side of the child component to the start of the container, regardless of scrolling velocity.
forceCenter– Align the center of the child component to the center of the container, regardless of scrolling velocity.
forceEnd– Align the ending side of the child component to the end of the container, regardless of scrolling velocity.
snap property applies when the user scrolls the content. The property doesn't apply to scrolling commands. To align items during command-driven scrolling, use the
ScrollToIndex command and set the
align property on the command.
Sequence is a multichild component. The
Sequence inherits all the multichild properties.
Sequence is an actionable component. The
Sequence inherits all the actionable properties.
Sequence event object
Sequence is the source or target of an event, the following values are reported in
// Sequence-specific values
"position": Number, // Scrolled position of the component, as a percentage
// Visible children
"firstVisibleChild": Integer, // Index of the first partially visible child
"firstFullyVisibleChild": Integer, // Index of the first fully visible child
"lastFullyVisibleChild": Integer, // Index of the last fully visible child
"lastVisibleChild": Integer, // Index of the last partially visible child
// General component values
"bind": Map, // Access to component data-binding context
"checked": Boolean, // Checked state
"disabled": Boolean, // Disabled state
"focused": Boolean, // Focused state
"height": Number, // Height of the component, in dp (includes the padding)
"id": ID, // ID of the component
"opacity": Number, // Opacity of the component [0-1]
"pressed": Boolean, // Pressed state
"uid": UID, // Runtime-generated unique ID of the component
"width": Number // Width of the component, in dp (includes the padding)
position value reported is the percentage of the current scroll position as expressed by the width or height of the sequence. This value is the same as the position reported by the
The event properties include ranges for visible children.
A child component is fully visible when all the following are true:
- The bounds of the child component don't extend outside of the default bounds of the
- The child component
displayproperty is "normal"
- The child component has an
A child component is visible, but not fully visible when all the following are true:
- The default bounds of child component intersect with the bounds of the sequence
- The child
displayproperty is "normal"
- The child has a non-zero
lastVisibleChild contains all the child components which have some part shown in the sequence. The range
lastFullyVisibleChild contains all the child components which are fully visible in the sequence.
lastVisibleChild properties return –1 if no children are visible in the sequence. The
lastFullyVisibleChild properties return –1 if no children are fully visible in the sequence.
The visibility calculations don't consider the child
transform property or occlusion by other components that might overlap the sequence.
The following example shows a
Sequence that displays a list of
Text components. As you scroll through the list, the text below the
Sequence updates to show some of the event object properties. Click the buttons to scroll to a specific index in the list. Click and drag in the
Sequence to scroll manually.
Sequence child items
The children of a sequence display in a continuous strip. The
Sequence arranges the items in either a horizontal or vertical direction:
- Horizontal – The items display in either a left-to-right or right-to-left order, depending on the value of the
layoutDirectionproperty. The user swipes the component left or right to scroll through the items.
- Vertical – The items display in a top-to-bottom order. The user swipes the component up and down to scroll through the items.
The dimension of the child along the scrolling axis is auto; that is, it wraps the content of the child by default.
The children of a
Sequence support the following additional properties.
Control ordinal numbering of the next child.
Additional space to add between this component and the previous component in the layout.
Applies when the
numbered set to
numbering property controls how the
Sequence updates the
ordinal value for the next child in the sequence.
normal: The next child
skip: The next child
reset: The next child
An amount of spacing to add between this component and the previous component in the sequence. The first item in the sequence ignores spacing. The value must be in absolute dimensions.
The following example shows a
Sequence that displays a
Text component. The example binds the
data property to an array of items, so the
Sequence uses data array inflation. Therefore, the
Sequence displays the child item one time for each item in the
The example also demonstrates the
lastItem properties. For the small, round hub, these properties define the header and footer. The header and footer scroll along with the rest of the list items. For all other viewports, the example uses a
Container for the header,
Sequence, and footer. The header and footer remain fixed on the screen all the time.
- Actionable Component Properties
- Multi-child Component Properties
- Alexa Design Guide: Alexa Presentation Language
Was this page helpful?
Last updated: Nov 28, 2023