material-components_material-components-android/docs/components/Slider.md

Slider

Sliders allow users to make selections from a range of values.

Contents

• Design & API Documentation
• Using sliders
• Continuous slider
• Discrete slider
• Theming sliders

Design & API Documentation

• Google Material3 Spec
• API Reference

Using sliders

Before you can use Material sliders, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Usage

Add a Slider to a layout:

<!-- Continuous slider -->
<com.google.android.material.slider.Slider
    ...
    android:valueFrom="0.0"
    android:valueTo="100.0"  />

<!-- Discrete slider -->
<com.google.android.material.slider.Slider
    ...
    android:valueFrom="0.0"
    android:valueTo="100.0"
    android:stepSize="10.0"  />

Observe changes to a slider:

slider.addOnSliderTouchListener(object : Slider.OnSliderTouchListener {
    override fun onStartTrackingTouch(slider: Slider) {
        // Responds to when slider's touch event is being started
    }

    override fun onStopTrackingTouch(slider: Slider) {
        // Responds to when slider's touch event is being stopped
    }
})

slider.addOnChangeListener { slider, value, fromUser ->
    // Responds to when slider's value is changed
}

API and source code:

• Slider
  • Class definition
  • Class source

A slider with two thumbs is called a range slider. Add a RangeSlider to a layout:

<!-- Continuous slider -->
<com.google.android.material.slider.RangeSlider
    ...
    android:valueFrom="0.0"
    android:valueTo="100.0"
    app:values="@array/initial_slider_values"  />

<!-- Discrete slider -->
<com.google.android.material.slider.RangeSlider
    ...
    android:valueFrom="0.0"
    android:valueTo="100.0"
    app:values="@array/initial_slider_values"
    android:stepSize="10.0"  />

And in values/arrays.xml:

<resources>
  <array name="initial_slider_values">
    <item>20.0</item>
    <item>70.0</item>
  </array>
</resources>

Observe changes to a range slider:

rangeSlider.addOnSliderTouchListener(object : RangeSlider.OnSliderTouchListener {
    override fun onStartTrackingTouch(slider: RangeSlider) {
        // Responds to when slider's touch event is being started
    }

    override fun onStopTrackingTouch(slider: RangeSlider) {
        // Responds to when slider's touch event is being stopped
    }
})

rangeSlider.addOnChangeListener { rangeSlider, value, fromUser ->
    // Responds to when slider's value is changed
}

API and source code:

• RangeSlider
  • Class definition
  • Class source

Making sliders accessible

Sliders support setting content descriptors for use with screen readers. While optional, we strongly encourage their use.

That can be done in XML via the android:contentDescription attribute or programmatically:

slider.contentDescription = contentDescription

If using a TextView to display the value of the slider, you should set android:labelFor so that screen readers announce that TextView refers to the slider.

The minimum touch target size of the thumb is 48dp by default. If a different size is needed, please set minTouchTargetSize in the style or the layout.

Adding/removing the value label

By default, the slider will show a value label above the thumb when it's selected. You can change how it's drawn via the app:labelBehavior attribute or setLabelBehavior method.

The modes of app:labelBehavior are:

• floating (default) - draws the label floating above the bounds of this view
• withinBounds - draws the label floating within the bounds of this view
• gone - prevents the label from being drawn
• visible - always draws the label

Note: there's a known issue where the label doesn't scroll along with the screen when the slider is in a scrollable container and app:labelBehavior=visible. To work around that you should either use a different mode or hide the label on scroll.

Setting a LabelFormatter

By using a LabelFormatter you can display the selected value using letters to indicate magnitude (e.g.: 1.5K, 3M, 12B). That can be achieved through the setLabelFormatter method.

The following example shows a slider for a price range in USD currency.

In code:

rangeSlider.setLabelFormatter { value: Float ->
    val format = NumberFormat.getCurrencyInstance()
    format.maximumFractionDigits = 0
    format.currency = Currency.getInstance("USD")
    format.format(value.toDouble())
}

Types

There are two types of sliders: 1. Continuous slider, 2. Discrete slider

Continuous slider

Continuous sliders allow users to make meaningful selections that don’t require a specific value.

The following example shows a continuous slider.

In the layout:

<com.google.android.material.slider.Slider
    android:id="@+id/slider"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:contentDescription="@string/slider_desc"
    android:value="20.0"
    android:valueFrom="0.0"
    android:valueTo="100.0" />

Continuous range slider

The following example shows a continuous range slider.

In the layout:

<com.google.android.material.slider.RangeSlider
  android:id="@+id/range_slider"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:contentDescription="@string/slider_desc"
  app:values="@array/initial_slider_values"
  android:valueFrom="0.0"
  android:valueTo="100.0" />

Discrete slider

Discrete sliders display a numeric value label upon pressing the thumb, which allows a user to input an exact value.

The following example shows a discrete slider.

In the layout:

<com.google.android.material.slider.Slider
    ...
    android:stepSize="10.0" />

Discrete range slider

The following example shows a discrete range slider.

In the layout:

<com.google.android.material.slider.RangeSlider
    ...
    android:stepSize="10.0"  />

Anatomy and key properties

A slider has a track, one or two thumbs, and an optional value label. A discrete slider also has tick marks.

1. Track
2. Thumb
3. Value label (optional)
4. Tick mark (discrete sliders)

Track attributes

Element	Attribute	Related method(s)	Default value
Min value	android:valueFrom	setValueFrom getValueFrom	N/A
Max value	android:valueTo	setValueTo getValueTo	N/A
Step size (discrete)	android:stepSize	setStepSize getStepSize	N/A
Initial selected value (Slider)	android:value	setValue getValue	N/A
Initial selected values (RangeSlider)	app:values	setValues getValues	N/A
Height	app:trackHeight	setTrackHeight getTrackHeight	4dp
Color	app:trackColor	setTrackTintList getTrackTintList	null
Color for track's active part	app:trackColorActive	setTrackActiveTintList getTrackActiveTintList	?attr/colorPrimary
Color for track's inactive part	app:trackColorInactive	setTrackInactiveTintList getTrackInactiveTintList	?attr/colorSurfaceContainerHighest
Minimum separation for adjacent thumbs	app:minSeparation	setMinSeparation getMinSeparation	0dp

Note: app:trackColor takes precedence over app:trackColorActive and app:trackColorInative. It's a shorthand for setting both values to the same thing.

Thumb attributes

Element	Attribute	Related method(s)	Default value
Color	app:thumbColor	setThumbTintList getThumbTintList	?attr/colorPrimary
Radius	app:thumbRadius	setThumbRadiusResource setThumbRadius getThumbRadius	10dp
Elevation	app:thumbElevation	setThumbElevationResource setThumbElevation getThumbElevation	2dp
Halo color	app:haloColor	setHaloTintList getHaloTintList	?attr/colorPrimary at 24%
Halo radius	app:haloRadius	setHaloRadiusResource setHaloRadius getHaloRadius	24dp
Stroke color	app:thumbStrokeColor	setThumbStrokeColor setThumbStrokeColorResource getThumbStrokeColor	null
Stroke width	app:thumbStrokeWidth	setThumbStrokeWidth setThumbStrokeWidthResource getThumbStrokeWidth	0dp

Value label attributes

Element	Attribute	Related method(s)	Default value
Style	app:labelStyle	N/A	@style/Widget.Material3.Tooltip
Formatter	N/A	setLabelFormatter hasLabelFormatter	null
Behavior	app:labelBehavior	setLabelBehavior getLabelBehavior	floating

Note: The value label is a Tooltip.

Tick mark attributes

Element	Attribute	Related method(s)	Default value
Color	app:tickColor	setTickTintList getTickTintList	null
Color for tick's active part	app:tickColorActive	setTickActiveTintList getTickActiveTintList	?attr/colorSurfaceVariant
Color for tick's inactive part	app:tickColorInactive	setTickInactiveTintList getTickInactiveTintList	?attr/colorPrimary
Radius for tick's active part	app:tickRadiusActive	setTickActiveRadius getTickActiveRadius	1dp
Radius for tick's inactive part	app:tickRadiusInactive	setTickInactiveRadius getTickInactiveRadius	1dp
Tick visible	app:tickVisible	setTickVisible isTickVisible()	true

Note: app:tickColor takes precedence over app:tickColorActive and app:tickColorInative. It's a shorthand for setting both values to the same thing.

Styles

Element	Style
Default style	Widget.Material3.Slider

Default style theme attribute: ?attr/sliderStyle

See the full list of styles and attributes.

Theming sliders

Sliders support Material Theming which can customize color and typography.

Slider theming example

API and source code:

• Slider
  • Class definition
  • Class source
• RangeSlider
  • Class definition
  • Class source

The following example shows a range slider with Material Theming.

Implementing slider theming

Use theme attributes and styles in res/values/styles.xml which applies to all sliders and affects other components:

<style name="Theme.App" parent="Theme.Material3.*">
    ...
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
    <item name="colorOnSurface">@color/shrine_pink_100</item>
</style>

Use a default style theme attribute, styles and a theme overlay which applies to all sliders but does not affect other components:

<style name="Theme.App" parent="Theme.Material3.*">
    ...
    <item name="sliderStyle">@style/Widget.App.Slider</item>
</style>

<style name="Widget.App.Slider" parent="Widget.Material3.Slider">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Slider</item>
    <item name="labelStyle">@style/Widget.App.Tooltip</item>
  </style>

<style name="ThemeOverlay.App.Slider" parent="">
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
    <item name="colorOnSurface">@color/shrine_pink_100</item>
</style>

<style name="Widget.App.Tooltip" parent="Widget.Material3.Tooltip">
    <item name="android:textAppearance">@style/TextAppearance.App.Tooltip</item>
    <item name="backgroundTint">@color/shrine_pink_900</item>
  </style>

<style name="TextAppearance.App.Tooltip" parent="TextAppearance.Material3.BodySmall">
  <item name="android:textColor">@color/shrine_pink_100</item>
  <item name="fontFamily">@font/rubik</item>
  <item name="android:fontFamily">@font/rubik</item>
</style>

Use the style in the layout, which affects only this specific slider:

<com.google.android.material.slider.RangeSlider
    ...
    style="@style/Widget.App.Slider"  />