Progress Bar

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

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)
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
`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.	Medium	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`.	Medium	1.2.0
`entities`	Array	—	Array of entity data to bind to this component.	Medium	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`.	Medium	1.2.0
`layoutDirection`	String	`${environment.layoutDirection}`	Specifies the layout direction for the progress bar. Set this property to either `LTR` (left-to-right) or `RTL` (right-to-left). This property doesn't inherit the `layoutDirection` from the component's parent container. Therefore, explicitly set this property when needed. For more details about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.	Not supported	1.4.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.	Medium	1.2.0
`progressFillColor`	Color	`@colorComponent`	Fill color to indicate progress of a `determinate` progress bar.	Medium	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.	Medium	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Medium	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.	Medium	1.2.0
`type`	String	—	Always set to `AlexaProgressBar`.	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).

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

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

Important: The indeterminate AlexaProgressBar style requires APL 1.4 or later. Provide an alternate experience for devices running older versions of APL.

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.

Important: 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.

Was this page helpful?

Provide feedback

Last updated: Dec 06, 2023