Slider

The Alexa slider responsive component (AlexaSlider) displays an interactive progress bar. Users can drag the bar to scrub content or change settings.

Important: AlexaSlider requires APL 1.4 or later. Provide an alternate experience for devices running older versions of APL.

Import the alexa-layouts package

To use AlexaSlider, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.3.0. AlexaSlider was introduced in version 1.2.0.

AlexaSlider parameters

All parameters except type and sliderId 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 completed for the slider. The slider represents this value by filling in with a lighter color. The buffer bar is visible when the `bufferValue` is larger than `progressValue`. Applies when `isLoading` is false.	1.2.0
`entities`	Array	[]	Array of entity data to bind to this component.	1.2.0
`handleKeyDownCommand`	Array of keyboard event handlers		Array of keyboard event handlers to run when the slider receives a key down from keyboard or D-PAD. See Run commands when the user interacts with the slider.	1.2.0
`iconLeftGraphicSource`	String	AlexaSliderVolumnOff	The URL or direct reference to a vector graphic an icon to display on the left side of the slider. Applies when `sliderType` is `icon`.	1.2.0
`iconRightGraphicSource`	String	AlexaSliderVolumn	The URL or direct reference to a vector graphic an icon to display on the right side of the slider. Applies when `sliderType` is `icon`.	1.2.0
`isLoading`	Boolean	false	When true, display an animation in the unfilled portion of the slider to indicate that content is loading.	1.2.0
`metadataDisplayed`	Boolean	false	When true, the slider displays the current `progressValue` and `totalValue` as a duration. Applies when `sliderType` is `default`. See Slider types.	1.2.0
`metadataPosition`	String	above_right	Sets the meta-data position for a `default` slider. Applies when `sliderType` is `default` and `metaDataDisplayed` is `true`. Set to `above_right`, `above_left_right`, or `below_left_right`.	1.2.0
`onBlurCommand`	Array of commands		Array of commands to run when the slider loses focus. See Run commands when the user interacts with the slider.	1.2.0
`onDownCommand`	Array of commands		Array of commands to run when an `onDown` event occurs. The `onDown` event occurs when the user touches or selects the slider. See Run commands when the user interacts with the slider.	1.2.0
`onFocusCommand`	Array of commands		Array of commands to run when the slider receives focus. See Run commands when the user interacts with the slider.	1.2.0
`onMoveCommand`	Array of commands		Array of commands to run when an `onMove` event occurs. The `onMove` event occurs when the user moves the thumb on slider. See Run commands when the user interacts with the slider.	1.2.0
`onUpCommand`	Array of commands		Array of commands to run when an `onUp` event occurs. The `onUp` event occurs when the user releases the slider. See Run commands when the user interacts with the slider.	1.2.0
`positionPropertyName`	String	Thumbposition	Name of the property used to return the current position of the slider thumb. You can use this in data-binding to determine the position as the user moves the slider. See Get the current thumb position.	1.2.0
`progressFillColor`	Color	@colorComponent	Fill color to indicate progress of the slider.	1.2.0
`progressValue`	Number	0	Value representing the completion of the slider. The slider represents this value by filling in with the color specified in `progressFillColor` and displaying the slider thumb at this position. You provide `progressValue` in milliseconds, although a `text` slider represents the value as a percentage.	1.2.0
`sliderId`	String	Slider	(Required) Unique identifier for this instance of `AlexaSlider`. The `AlexaSlider` component uses this ID internally. If you need to refer to the component within your document from other components, you must also set the base component `id` property.	1.2.0
`sliderMoveMillisecond`	Number	10000	Time in milliseconds to move the slider when using a keyboard or D-pad.	1.2.0
`sliderSize`	String	small	Set the size for the indicators shown at each end of the slider. Applies when `sliderType` is `icon` or `text`. Set to `small`, `medium`, or `large`.	1.2.0
`sliderType`	String	default	Determines whether the slider shows a duration, icons (such as volume indicators), or percentage. Set to `default`, `icon`, or `text`. See Slider types.	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
`thumbColor`	Color	@colorComponent	Color for the slider thumb icon.	1.2.0
`thumbDisplayedAllStates`	Boolean	true	When true, the slider thumb icon always displays. When false, hide the thumb icon until the user interacts with the slider to move it backwards or forwards.	1.2.0
`totalValue`	Number	0	Value in milliseconds for the total duration the slider represents. For example, set `totalValue` to 100,000 to create a slider that represents 1 minute, 40 seconds of time. Note that the total time doesn't determine the width of the bar drawn on the screen. Use the standard `width` property on `AlexaSlider` or on its parent `Container` to determine the size of the bar.	1.2.0

Slider types

The sliderType determines the overall appearance of the slider. AlexaSlider supports the following three types:

default – The slider indicates a duration of time. You can set metadataDisplayed to display the total time the bar represents along with the current progress.
icon – The slider represents a setting or value with a range. The slider uses icons at either end to indicate the meaning. For example, a slider that represents a volume setting would show a "volume off" icon on the left and a "volume full" icon on the right.
text – The slider indicates a percentage. The slider displays "0%" on the left and "100%" on the right. As the user moves the slider, the value on the left end updates to reflect the current percentage.

The following image illustrates the slider types. The first two shown use the default style, the third is an icon slider with the default volume icons, and the last is a text slider.

Although the three slider types present the information differently, they all use milliseconds to represent the total time and current progress on the slider:

Set totalValue to the total number of milliseconds.
Set progressValue to the number of milliseconds to fill in with color to show progress on the bar. This value also determines the position of the slider thumb. When the user moves the slider, the new value overrides the original value for this property.
Set bufferValue to the number of milliseconds to fill in with a secondary color to show progress of the buffer.

Slider size

Use the sliderSize to set the size of the icons and text for the icon and text slider types. This property changes the size of the icons or percentages shown on either end of the slider.

Use the base component width property to control the length of the slider. Set the width on the AlexaSlider component itself, or on its parent Container. The viewport size determines the height or thickness of the bar. You can't change this value.

The following image illustrates the small, medium, and large settings for sliderSize for both the icon and text sliders.

Copied to clipboard.

To learn how to test APL examples in the authoring tool, see Experiment with APL Examples in the Authoring Tool

{
  "type": "APL",
  "version": "1.6",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.3.0"
    }
  ],
  "mainTemplate": {
    "items": {
      "type": "Container",
      "justifyContent": "center",
      "paddingLeft": "@marginHorizontal",
      "paddingRight": "@marginHorizontal",
      "items": [
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "icon",
          "sliderSize": "small"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "icon",
          "sliderSize": "medium"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "icon",
          "sliderSize": "large"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "text",
          "sliderSize": "small"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "text",
          "sliderSize": "medium"
        },
        {
          "type": "AlexaSlider",
          "theme": "${viewport.theme}",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "text",
          "sliderSize": "large"
        }
      ]
    }
  }
}

Run commands when the user interacts with the slider

The AlexaSlider is both an actionable component and a touchable component. This means it has additional properties to handle user actions and touch events, such as an onMove handler. AlexaSlider uses these handlers to make the slider interactive.

You can optionally provide additional commands to run for these handlers so that you can respond when the user interacts with the slider. Each of the following properties takes an array of commands to run when the corresponding event occurs:

handleKeyDownCommand
onBlurCommand
onDownCommand
onFocusCommand
onMoveCommand
onUpCommand

The commands you pass to these properties run in addition to the commands intended to make the slider interactive.

For example, the following command sets the value of a property called handlerName to the string "onMove" when the user moves the slider.

{
  "onMoveCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onMove"
  }
}

For an example that uses this command, see AlexaSlider example.

Get the current thumb position

You set the initial thumb position on the slider with the progressValue property. As the user interacts with the slider, the current thumb position changes. You can access this value within the commands you define.

To get the current thumb position as the user moves the slider

Set the positionPropertyName to a name that represents the thumb position. The default name for this property is Thumbposition.
Create a binding for this property with the bind property. This lets you access the property from other components in your document.
In your commands, reference the bound variable with data-binding syntax.

For example, the following Container creates two bindings: one for Thumbposition and one for a variable called handlerName:

{
  "type": "Container",
  "bind": [
    {
      "name": "Thumbposition",
      "value": 0
    },
    {
      "name": "handlerName",
      "value": "none"
    }
  ],
  "items": []
}

Then this Container has a Text property that displays each of these values:

{
  "type": "Text",
  "text": "Thumbposition = ${Thumbposition}, handlerName = ${handlerName}",
  "style": "textStyleDisplay6"
}

Next, the AlexaSlider component sets the positionPropertyName to Thumbposition and defines a SetValue command on each handler. When the user interacts with the slider, the Text component displays the current Thumbposition and the name of the active handler.

{
  "type": "AlexaSlider",
  "sliderId": "Slider",
  "progressValue": 0,
  "totalValue": 100000,
  "sliderMoveMillisecond": 10000,
  "progressFillColor": "red",
  "thumbColor": "green",
  "positionPropertyName": "Thumbposition",
  "thumbDisplayedAllStates": true,
  "metadataDisplayed": true,
  "onMoveCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onMove"
  },
  "onUpCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onUp"
  },
  "onDownCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onDown"
  },
  "onFocusCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onFocus"
  },
  "onBlurCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onBlur"
  },
  "handleKeyDownCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "handleKeyDown"
  }
}

For an example of a complete document that uses this technique, see AlexaSlider example.

AlexaSlider example

The following example illustrates a complete document with a slider that updates text as the user moves the thumb. The button then resets the slider to 0.