Progress Bar Radial
The Alexa progress bar responsive component (AlexaProgressBarRadial
) displays a circular progress bar to indicate ongoing activity. You can choose from different styles to communicate different types of activity progress. Use this component on small round hubs, such as the Echo Spot.
Compatibility
AlexaProgressBarRadial
is designed to work with the following standard viewport profiles in the alexa-viewport-profiles
package:
- All hub round profiles
If you use AlexaProgressBarRadial
on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.
Import the alexa-layouts package
To use AlexaProgressBarRadial
, import the alexa-layouts package.
The latest version of the alexa-layouts
package is 1.7.0. AlexaProgressBarRadial
was introduced in version 1.2.0.
AlexaProgressBarRadial parameters
All parameters except type
are optional.
Name | Type | Default | Description | Widget support | Version added |
---|---|---|---|---|---|
|
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. |
Not supported |
1.2.0 |
|
Number |
0 |
Value representing the amount of buffer time that has passed for a |
Not supported |
1.2.0 |
|
Array |
— |
Array of entity data to bind to this component. |
Not supported |
1.2.0 |
|
String |
|
Determines the type of progress bar to display. Set to |
Not supported |
1.2.0 |
|
Fill color to indicate progress of a |
Not supported |
1.2.0 | ||
|
Number |
0 |
Value representing the amount of time that has passed for a |
Not supported |
1.2.0 |
|
String |
|
Set the dark or light color theme. The selected theme controls the colors used for the component. |
Not supported |
1.2.0 |
|
Number |
0 |
Value in milliseconds for the total duration the progress bar represents. For example, set |
Not supported |
1.2.0 |
Position the progress bar on a round viewport
Use the when
property to display AlexaProgressBarRadial
on small round hubs.
"when": "${@viewportProfile == @hubRoundSmall}"
The component isn't designed to display on rectangular hubs. For a rectangular hub, use AlexaProgressBar
instead.
To include other components on the viewport, place AlexaProgressBarRadial
in a Container
and set position
to absolute
. Then include the other components after AlexaProgressBarRadial
. This lets the other components overlap and display on top of the progress bar component. The components then appear inside the circular progress bar.
The following example illustrates a conditional Container
that displays a progress bar and a Text
component. The Text
component displays content from a data source.
{
"when": "${@viewportProfile == @hubRoundSmall}",
"type": "Container",
"height": "100%",
"width": "100%",
"items": [
{
"type": "AlexaProgressBarRadial",
"id": "roundHubBar",
"progressBarType": "indeterminate",
"position": "absolute"
},
{
"type": "Text",
"height": "100%",
"textAlignVertical": "center",
"textAlign": "center",
"text": "${progressBarRadialExample.textToShow}"
}
]
}
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 AlexaProgressBarRadial
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": "AlexaProgressBarRadial",
"progressValue": "0",
"totalValue": "100000",
"progressFillColor": "blue",
"position": "absolute",
"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.
AlexaProgressBarRadial example
This example illustrates a complete document that displays an AlexaProgressBarRadial
on a small round hub, and an AlexaProgressBar
on all other viewports. The example uses a data source to display the same values in both the round and rectangular layouts. Switch to a different viewport to see the same data displayed in an AlexaProgressBar
.
Related topics
- Alexa Design System Overview
- Responsive Components and Templates
- Alexa Progress Bar
- Alexa Design Guide: Responsive Components
Last updated: Nov 28, 2023