Slider (1.2.0 - 1.3.0)

(This is not the most recent version of AlexaSlider. Use the Other Versions option to see the documentation for the most recent version of AlexaSlider)

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

Import the alexa-layouts package

To use AlexaSlider, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.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.

AlexaSlider examples
AlexaSlider examples

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.

AlexaSlider examples
AlexaSlider examples

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

  1. Set the positionPropertyName to a name that represents the thumb position. The default name for this property is Thumbposition.
  2. Create a binding for this property with the bind property. This lets you access the property from other components in your document.
  3. 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.

Example of updating a Text component when the user moves the slider
Example of updating a Text component when the user moves the slider
Was this page helpful?

Last updated: Nov 28, 2023