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.

Compatibility

AlexaSliderRadial is designed to work with the following standard viewport profiles in the alexa-viewport-profiles package:

  • All hub round profiles

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

Import the alexa-layouts package

To use AlexaSliderRadial, import the alexa-layouts package.

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

AlexaSliderRadial parameters

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.

Not supported

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.

Not supported

1.2.0

entities

Array

Array of entity data to bind to this component.

Not supported

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.

Not supported

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.

Not supported

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.

Not supported

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.

Not supported

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.

Not supported

1.2.0

progressFillColor

Color

@colorComponent

Fill color to indicate progress of the slider.

Not supported

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.

Not supported

1.2.0

theme

String

dark

Set the dark or light color theme. The selected theme controls the colors used for the component.

Not supported

1.2.0

thumbColor

Color

@colorComponent

Color for the slider thumb icon.

Not supported

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.

Not supported

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.

Not supported

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.

Not supported

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. You can place other components before or after AlexaSliderRadial to display them inside. Make sure that any components after the AlexaSliderRadial in the Container are small enough that they don't overlap the interactive portion of the slider. A component that overlaps the interactive part of the slider interferes with moving the 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": "Text",
      "height": "100%",
      "paddingLeft": "@marginHorizontal",
      "paddingRight": "@marginHorizontal",
      "textAlignVertical": "center",
      "textAlign": "center",
      "text": "${sliderRadialExample.textToShow}"
    },
    {
      "type": "AlexaSliderRadial",
      "progressValue": "${sliderRadialExample.progressValue}",
      "bufferValue": "${sliderRadialExample.bufferValue}",
      "totalValue": "${sliderRadialExample.totalValue}",
      "progressFillColor": "blue",
      "position": "absolute"
    }    
  ]
}

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

Run 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 run when the corresponding event occurs:

  • onDownCommand
  • onMoveCommand
  • onUpCommand

The commands you pass to these properties run 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"
}

The following example displays the thumb position in a Text component in the center of the slider. The Text component is small enough that it doesn't overlap the interactive part of AlexaSlider.


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.



Was this page helpful?

Last updated: Nov 28, 2023