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.
Compatibility
AlexaProgressBar
is designed to work with the following viewport profiles:
- The following widget viewport profiles in the
alexa-viewport-profiles
package:- Widget Medium (
@hubWidgetMedium
)
- Widget Medium (
- All standard viewport profiles in the
alexa-viewport-profiles
package:- All hub round profiles
- All hub landscape profiles
- All hub portrait profiles
- All mobile profiles
- All TV profiles
For details about viewport profiles, see Viewport Profiles.
Differences for widgets
When used within a widget, AlexaProgressBar
doesn't support the right-to-left orientation (layoutDirection
).
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
The following table shows the parameters you can set on AlexaProgressBar
. Unless otherwise noted, standard viewport profiles support all parameters. The "Widget support" column indicates the widget viewport profiles that support each parameter. For details about viewport profiles, see Viewport Profiles.
All parameters except type
are optional.
Name | Type | Default | Description | Widget support | Version added |
---|---|---|---|---|---|
|
String |
{Progress} out of {Total}. |
A string describing the progress bar. Voice over reads this string when the user selects this component. |
Medium |
1.2.0 |
|
Number |
0 |
Value representing the amount of buffer time that has passed for a |
Medium |
1.2.0 |
|
Array |
— |
Array of entity data to bind to this component. |
Medium |
1.2.0 |
|
Boolean |
|
When |
Medium |
1.2.0 |
|
String |
|
Specifies the layout direction for the progress bar. Set this property to either |
Not supported |
1.4.0 |
|
String |
|
Determines the type of progress bar to display. Set to |
Medium |
1.2.0 |
|
Fill color to indicate progress of a |
Medium |
1.2.0 | ||
|
Number |
0 |
Value representing the amount of time that has passed for a |
Medium |
1.2.0 |
|
String |
|
Set the dark or light color theme. The selected theme controls the colors used for the component. |
Medium |
1.2.0 |
|
Number |
0 |
Value in milliseconds for the total duration the progress bar represents. For example, set |
Medium |
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. To restart the animation, refresh the page.
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 examples
The following example shows five different progress bars. To restart the animation, refresh the page.
The following example shows a progress bar that shows the progress of a timer. Click the button to start the timer. The timer uses the elapsedTime
property in the data-binding context to track the progress and a tick handler to reset the timer three seconds after it finishes.
The following example shows a widget that displays different styles of progress bars. To restart the animation, refresh the page.
Related topics
- Alexa Design System Overview
- Responsive Components and Templates
- Alexa Design Guide: Responsive Components
Last updated: Dec 06, 2023