Slider Radial

The Alexa slider responsive component (AlexaSliderRadial) displays a circular, interactive progress bar. Users can drag the bar to scrub content or change settings. Use this component on small round hubs, such as the Echo Spot.

Import the alexa-layouts package

To use AlexaSliderRadial, import the alexa-layouts package.

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

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

1.2.0

entities

Array

[]

Array of entity data to bind to this component.

1.2.0

metadataDisplayed

Boolean

false

When true, the slider displays the current progressValue and totalValue, depending on the value of thumbDisplayedAllStates.

When both properties are true, the slider always displays meta-data.

When metaDataDisplayed is true and thumbDisplayedAllStates is false, the slider displays meta-data during the onDown and onMove events and hides the meta-data during onUp.

When metaDataDisplayed is false, the slider never displays the meta-data.

1.2.0

onDownCommand

Array of commands

Array of commands to execute when an onDown event occurs. The onDown event occurs when the user touches or selects the slider. See Execute commands when the user interacts with the slider.

1.2.0

onMoveCommand

Array of commands

Array of commands to execute when an onMove event occurs. The onMove event occurs when the user moves the thumb on slider. See Execute commands when the user interacts with the slider.

1.2.0

onUpCommand

Array of commands

Array of commands to execute when an onUp event occurs. The onUp event occurs when the user releases the slider. See Execute 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.

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. See Slider active and inactive states.

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 one minute, 40 seconds of time. Note that this value has no affect on the size of the slider. The slider is always the circumference of the small round viewport.

1.2.0

useDefaultSliderExpandTransition

Boolean

true

When true, use a default animation to transition between the inactive progress bar view and the interactive slider. Applies when thumbDisplayedAllStates is false. When useDefaultSliderExpandTransition is false, the slider does not automatically transition back to the inactive progress bar view after the user interacts with it. See Slider active and inactive states.

Position the slider on a round viewport

Use the when property to display AlexaSliderRadial on small round hubs.

"when": "${@viewportProfile == @hubRoundSmall}"

The component isn't designed to display on rectangular hubs. For a rectangular hub, use AlexaSlider instead.

To include other components on the viewport, place AlexaSliderRadial in a Container and set position to absolute. Then include the other components after AlexaSliderRadial. This lets the other components overlap and display on top of the slider component. The components then appear inside the circular slider.

The following example illustrates a conditional Container that displays the slider and a Text component. The Text component displays content from a data source.

{
  "when": "${@viewportProfile == @hubRoundSmall}",
  "type": "Container",
  "height": "100%",
  "width": "100%",
  "items": [
    {
      "type": "AlexaSliderRadial",
      "progressValue": "${sliderRadialExample.progressValue}",
      "bufferValue": "${sliderRadialExample.bufferValue}",
      "totalValue": "${sliderRadialExample.totalValue}",
      "progressFillColor": "blue",
      "position": "absolute"
    },
    {
      "type": "Text",
      "height": "100%",
      "paddingLeft": "@marginHorizontal",
      "paddingRight": "@marginHorizontal",
      "textAlignVertical": "center",
      "textAlign": "center",
      "text": "${sliderRadialExample.textToShow}"
    }
  ]
}

For a complete document and data source with this example, see AlexaSliderRadial example.

Slider active and inactive states

The AlexaSliderRadial displays in two states:

  • Active slider – The slider displays inside the borders of the round hub and includes the thumb icon. The user can drag the icon to move the slider position.
  • Inactive progress bar – The slider hides the thumb icon and expands to the edges of the small, round hub. In this state, the slider looks the same as the AlexaProgressBarRadial component. When the user selects the slider, it transitions to the active state.
AlexaSliderRadial in the active state
AlexaSliderRadial in the active state
AlexaSliderRadial in the inactive state
AlexaSliderRadial in the inactive state

You can set options that control how the slider shifts between these states.

Always display the active slider

To keep the slider in the active state, set the thumbDisplayedAllStates property to true. The slider always displays in the "shrunk" version with the thumb icon.

Automatically shift between states

To automatically shift the slider between the active and inactive states when the user interacts with the slider, set both of the following properties:

  • Set thumbDisplayedAllStates to false.
  • Set useDefaultSliderExpandTransition to true.

The slider initially displays in the inactive progress bar state. When the user selects the slider, it shrinks to the active state and displays the thumb icon. After the user releases the slider, it reverts to the inactive progress bar version. Note that there might be a delay of a few seconds before the slider shifts back to the inactive state.

Manually set the state with commands

You can execute commands to change the slider state manually:

  • AlexaSliderRadialShrink – Transitions the slider to the active state and displays the thumb icon.
      {
        "type": "AlexaSliderRadialShrink"
      }
    
  • AlexaSliderRadialExpand – Transitions the slider to the inactive state.

      {
        "type": "AlexaSliderRadialExpand"
      }
    
  • AlexaSliderRadialMetadataControl – Hides or displays the slider metadata. Set show to true to fade the metadata into view. Set show to false to fade out the metadata.
      {
        "type": "AlexaSliderRadialMetadataControl",
        "show": true
      }
    

The following example creates a button that shifts the slider into the active state and displays the current metadata.

{
  "type": "AlexaButton",
  "buttonText": "Shrink the slider",
  "alignSelf": "center",
  "primaryAction": {
    "type": "Parallel",
    "commands": [
      {
        "type": "AlexaSliderRadialShrink"
      },
      {
        "type": "AlexaSliderRadialMetadataControl",
        "show": true
      }
    ]
  }
}

Execute commands when the user interacts with the slider

The AlexaSliderRadial 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. AlexaSliderRadial 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 execute when the corresponding event occurs:

  • onDownCommand
  • onMoveCommand
  • onUpCommand

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

The following example updates a text component as the user selects, moves, and releases the slider.

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 property to a name that represents the thumb position. The default value 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 a binding for Thumbposition:

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

Then this Container has a Text property that displays this value:

{
  "type": "Text",
  "text": "Thumbposition =<br>${Thumbposition}",
  "textAlign": "center",
  "style": "textStyleBody"
}

Next, the AlexaSliderRadial component sets the positionPropertyName to Thumbposition. When the user interacts with the slider, the Text component displays the current Thumbposition.

{
  "type": "AlexaSliderRadial",
  "progressValue": 0,
  "totalValue": 100000,
  "thumbDisplayedAllStates": true,
  "positionPropertyName": "Thumbposition",
  "metadataDisplayed": true,
  "position": "absolute"
}

AlexaSliderRadial example

This example illustrates a complete document that displays an AlexaSliderRadial on a small round hub, and an AlexaSlider on all other viewports. The example uses a data source to display the same values in both the round and rectangular layouts.

AlexaSliderRadial
Display AlexaSliderRadial on small, round hubs
AlexaSliderRadial
Display AlexaSlider on rectangular hubs