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

accessibilityLabel

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

bufferValue

Number

0

Value representing the amount of buffer time that has passed for a determinate progress bar. The progress bar represents this value by filling in with a lighter color. The buffer bar is visible when the bufferValue is larger than progressValue. Applies when progressBarType is determinate and isLoading is false.

Not supported

1.2.0

entities

Array

—

Array of entity data to bind to this component.

Not supported

1.2.0

progressBarType

String

determinate

Determines the type of progress bar to display. Set to determinate or indeterminate.

determinate – the bar represents a set amount of time. You update the progressValue property with the elapsed time to fill the bar.

indeterminate – the progress bar displays an animation indicating ongoing activity, but the bar isn't connected to time.

Not supported

1.2.0

progressFillColor

Color

@colorComponent

Fill color to indicate progress of a determinate progress bar.

Not supported

1.2.0

progressValue

Number

0

Value representing the amount of time that has passed for a determinate progress bar. The progress bar represents this value by filling in with the color specified in progressFillColor. Applies when progressBarType is determinate. For details about updating this property to show ongoing progress, see Advancing a determinate progress bar.

Not supported

1.2.0

theme

String

dark

Set the dark or light color theme. The selected theme controls the colors used for the component.

Not supported

1.2.0

totalValue

Number

0

Value in milliseconds for the total duration the progress bar represents. For example, set totalValue to 100,000 to create a progress bar that represents 1 minute, 40 seconds of time. Note that this value has no affect on the size of the bar. The progress bar is always the circumference of the small round viewport.

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.

Copied to clipboard.

{
  "type": "AlexaProgressBarRadial",
  "progressValue": "0",
  "totalValue": "100000",
  "progressFillColor": "blue",
  "position": "absolute",
  "handleTick": [
    {
      "when": "${progressValue < totalValue}",
      "minimumDelay": 1000,
      "commands": [
        {
          "type": "SetValue",
          "property": "progressValue",
          "value": "${progressValue + 1000}"
        }
      ]
    }
  ]
}

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.

Last updated: Mar 02, 2023