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.

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.

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.

Related topics

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

Last updated: Nov 28, 2023