# Slider
[Sliders](https://m3.material.io/components/sliders/) allow users to make
selections from a range of values.
**Contents**
* [Design & API Documentation](#design-api-documentation)
* [Using sliders](#using-sliders)
* [Continuous slider](#continuous-slider)
* [Discrete slider](#discrete-slider)
* [Theming sliders](#theming-sliders)
## Design & API Documentation
* [Google Material3 Spec](https://material.io/components/sliders/overview)
* [API Reference](https://developer.android.com/reference/com/google/android/material/slider/package-summary)
## 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](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
page.
### Usage
Add a `Slider` to a layout:
```xml
```
Observe changes to a slider:
```kt
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](https://developer.android.com/reference/com/google/android/material/slider/Slider)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/slider/Slider.java)
A slider with two thumbs is called a range slider.
Add a `RangeSlider` to a layout:
```xml
```
And in `values/arrays.xml`:
```xml
- 20.0
- 70.0
```
Observe changes to a range slider:
```kt
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](https://developer.android.com/reference/com/google/android/material/slider/RangeSlider)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/slider/RangeSlider.java)
### 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:
```kt
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:
```kt
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](#continuous-slider), 2\.
[Discrete slider](#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:
```xml
```
### Continuous range slider
The following example shows a continuous range slider.
In the layout:
```xml
```
## 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:
```xml
```
### Discrete range slider
The following example shows a discrete range slider.
In the layout:
```xml
```
### 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](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tooltip/TooltipDrawable.java).
#### 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](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/slider/res/values/styles.xml)
and
[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/slider/res/values/attrs.xml).
## Theming sliders
Sliders support
[Material Theming](https://material.io/components/sliders#theming) which can
customize color and typography.
### Slider theming example
API and source code:
* `Slider`
* [Class definition](https://developer.android.com/reference/com/google/android/material/slider/Slider)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/slider/Slider.java)
* `RangeSlider`
* [Class definition](https://developer.android.com/reference/com/google/android/material/slider/RangeSlider)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/slider/RangeSlider.java)
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:
```xml
```
Use a default style theme attribute, styles and a theme overlay which applies to
all sliders but does not affect other components:
```xml
```
Use the style in the layout, which affects only this specific slider:
```xml
```