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

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.

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.

1.2.0

entities

Array

Array of entity data to bind to this component.

1.2.0

isLoading

Boolean

false

When true, display an animation in the unfilled portion of a determinate progress bar to indicate that content is loading. Applies when progressBarType is determinate.

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.

1.2.0

progressFillColor

Color

@colorComponent

Fill color to indicate progress of a determinate progress bar.

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.

1.2.0

theme

String

dark

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

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: The total time doesn't determine the width of the bar drawn on the screen. Use the standard width property on AlexaProgressBar or on its parent Container to determine the size of the bar.

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).

Determinate progress bars in different widths
Determinate progress bars in different widths

Copied to clipboard.

{
  "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.

Indeterminate progress bars in different widths
Indeterminate progress bars in different widths

Copied to clipboard.

{
  "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.

Copied to clipboard.

{
  "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}"
        }
      ]
    }
  ]
}

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.

Four examples of AlexaProgressBar
Four examples of AlexaProgressBar

Was this page helpful?

Last updated: Nov 28, 2023