Slider

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

Compatibility

AlexaSlider is designed to work with 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

If you use AlexaSlider on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

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.

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 example shows different slider types. The first two 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 examples show the small, medium, and large settings for sliderSize for both the icon and text sliders.

Icon sliders in small, medium, and large

Text sliders in small, medium, and 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

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.

Related topics

• Alexa Design System Overview
• Responsive Components and Templates
• Alexa Design Guide: Responsive Components

Last updated: Nov 28, 2023