Progress Bar (1.2.0 - 1.3.0)
(This is not the most recent version of AlexaProgressBar
. Use the Other Versions option to see the documentation for the most recent version of AlexaProgressBar
)
The Alexa progress bar responsive component (AlexaProgressBar
) displays a progress bar to indicate ongoing activity. You can choose from different styles to communicate different types of activity progress.
Import the alexa-layouts package
To use AlexaProgressBar
, import the alexa-layouts package.
The latest version of the alexa-layouts
package is 1.7.0. AlexaProgressBar
was introduced in version 1.2.0.
AlexaProgressBar parameters
All parameters except type
are optional.
Name | Type | Default | Description | Version added/updated |
---|---|---|---|---|
|
String |
{Progress} out of {Total}. |
A string describing the progress bar. Voice over reads this string when the user selects this component. |
1.2.0 |
|
Number |
0 |
Value representing the amount of buffer time that has passed for a |
1.2.0 |
|
Array |
— |
Array of entity data to bind to this component. |
1.2.0 |
|
Boolean |
|
When |
1.2.0 |
|
String |
|
Determines the type of progress bar to display. Set to |
1.2.0 |
|
Fill color to indicate progress of a |
1.2.0 |
||
|
Number |
0 |
Value representing the amount of time that has passed for a |
1.2.0 |
|
String |
|
Set the dark or light color theme. The selected theme controls the colors used for the component. |
1.2.0 |
|
Number |
0 |
Value in milliseconds for the total duration the progress bar represents. For example, set |
1.2.0 |
Progress bar size
Use the base component width
property to control the length of the progress bar. Set the width
on the AlexaProgressBar
component itself, or on its parent Container
. The viewport size determines the height or thickness of the bar. You can't change this value.
For example, the following image illustrates three determinate progress bars with different width
values. Each bar represents two minutes of time (120,000 milliseconds) and indicates that one minute has elapsed (60,000 milliseconds).
{
"type": "Container",
"width": "100%",
"height": "100%",
"justifyContent": "center",
"paddingLeft": "@marginHorizontal",
"paddingRight": "@marginHorizontal",
"items": [
{
"type": "AlexaProgressBar",
"progressValue": "60000",
"bufferValue": 70000,
"totalValue": 120000,
"width": "50%"
},
{
"type": "AlexaProgressBar",
"progressValue": "60000",
"bufferValue": 70000,
"totalValue": 120000,
"spacing": "@spacingLarge",
"width": "70%"
},
{
"type": "AlexaProgressBar",
"progressValue": "60000",
"bufferValue": 70000,
"totalValue": 120000,
"spacing": "@spacingLarge"
}
]
}
The following image illustrates three indeterminate progress bars with different width
values. Copy the sample JSON to the authoring tool to see the animation.
{
"type": "Container",
"width": "100%",
"height": "100%",
"justifyContent": "center",
"paddingLeft": "@marginHorizontal",
"paddingRight": "@marginHorizontal",
"items": [
{
"type": "AlexaProgressBar",
"progressBarType": "indeterminate",
"width": "50%"
},
{
"type": "AlexaProgressBar",
"progressBarType": "indeterminate",
"spacing": "@spacingLarge",
"width": "70%"
},
{
"type": "AlexaProgressBar",
"progressBarType": "indeterminate",
"spacing": "@spacingLarge"
}
]
}
Advancing a determinate progress bar
For a determinate progress bar, update the progressValue
and bufferValue
properties to fill in the bar with color. Use the SetValue
command to change the values.
The following example sets the progressValue
property for the AlexaProgressBar
with the id
"myProgressBar" to 40,000.
{
"type": "SetValue",
"componentId": "myProgressBar",
"property": "progressValue",
"value": 40000
}
To create a progress bar that advances automatically based on time, define a tick event handler that runs SetValue
. APL generates tick events as time passes. Use the handleTick
property to define an array of commands to run at each tick.
The following example updates progressValue
approximately one time each second until the progress bar is full.
{
"type": "AlexaProgressBar",
"progressValue": 0,
"bufferValue": 0,
"totalValue": 120000,
"progressFillColor": "blue",
"spacing": "@spacingXLarge",
"handleTick": [
{
"when": "${progressValue < totalValue}",
"minimumDelay": 1000,
"commands": [
{
"type": "SetValue",
"property": "progressValue",
"value": "${progressValue + 1000}"
}
]
}
]
}
handleTick
requires APL 1.4 or later. Provide an alternate experience for devices running older versions of APL.For more about handleTick
, see Tick Event Handlers.
AlexaProgressBar example
This example illustrates a complete document that displays different styles of progress bars.
To see the animation, copy the sample JSON into the authoring tool.
Related topics
Last updated: Nov 28, 2023