Progress Bar
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.2.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]". For example [20 seconds] out of [2 minutes]. |
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 |
false |
When true, display an animation in the unfilled portion of a |
1.2.0 |
|
|
String |
determinate |
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 |
dark |
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 executes SetValue. APL generates tick events as time passes. Use the handleTick property to define an array of commands to execute 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.
