1 |
|
2 | title: "Sliders"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "Sliders allow users to make selections from a range of values."
|
6 | iconId: slider
|
7 | path: /catalog/input-controls/sliders/
|
8 | -->
|
9 |
|
10 | # Slider
|
11 |
|
12 | [Sliders](https://material.io/components/sliders/) allow users to make
|
13 | selections from a range of values.
|
14 |
|
15 | The MDC Slider implementation supports both single point sliders (one thumb)
|
16 | and range sliders (two thumbs). It is backed by the browser
|
17 | `<input type="range">` element, is fully accessible, and is RTL-aware.
|
18 |
|
19 | **Contents**
|
20 |
|
21 | * [Using sliders](#using-sliders)
|
22 | * [Sliders](#sliders)
|
23 | * [Other variants](#other-variants)
|
24 | * [Additional information](#additional-information)
|
25 | * [API](#api)
|
26 |
|
27 | ## Using sliders
|
28 |
|
29 | ### Installing sliders
|
30 |
|
31 | ```
|
32 | npm install @material/slider
|
33 | ```
|
34 |
|
35 | ### Styles
|
36 |
|
37 | ```scss
|
38 | @use "@material/slider/styles";
|
39 | ```
|
40 |
|
41 | ### JavaScript instantiation
|
42 |
|
43 | ```js
|
44 | import {MDCSlider} from '@material/slider';
|
45 |
|
46 | const slider = new MDCSlider(document.querySelector('.mdc-slider'));
|
47 | ```
|
48 |
|
49 | **Note**: See [Importing the JS component](../../docs/importing-js.md) for more
|
50 | information on how to import JavaScript.
|
51 |
|
52 | ### Making sliders accessible
|
53 |
|
54 | Sliders are backed by an `<input>` element, meaning that they are fully
|
55 | accessible. Unlike the [ARIA-based slider](https://www.w3.org/TR/wai-aria-practices/#slider),
|
56 | MDC sliders are adjustable using touch-based assistive technologies such as
|
57 | TalkBack on Android.
|
58 |
|
59 | Per the spec, ensure that the following attributes are added to the
|
60 | `input` element(s):
|
61 |
|
62 | * `value`: Value representing the current value.
|
63 | * `min`: Value representing the minimum allowed value.
|
64 | * `max`: Value representing the maximum allowed value.
|
65 | * `aria-label` or `aria-labelledby`: Accessible label for the slider.
|
66 |
|
67 | If the value is not user-friendly (e.g. a number to
|
68 | represent the day of the week), also set the following:
|
69 |
|
70 | * `aria-valuetext`: Set this input attribute to a string that makes the slider
|
71 | value understandable, e.g. 'Monday'.
|
72 | * Add a function to map the slider value to `aria-valuetext` via the
|
73 | `MDCSlider#setValueToAriaValueTextFn` method.
|
74 |
|
75 | ## Sliders
|
76 |
|
77 | There are two types of sliders:
|
78 |
|
79 | 1. [Continuous slider](#continuous-slider)
|
80 | 1. [Discrete slider](#discrete-slider)
|
81 |
|
82 | ### Continuous slider
|
83 |
|
84 | Continuous sliders allow users to make meaningful selections that don’t require
|
85 | a specific value.
|
86 |
|
87 | Note: The step size for value quantization is, by default, 1. To specify
|
88 | a custom step size, provide a value for the `step` attribute on the `input`
|
89 | element.
|
90 |
|
91 | <img src="images/continuous-slider.png" alt="Continuous slider with a value of 50">
|
92 |
|
93 | ```html
|
94 | <div class="mdc-slider">
|
95 | <input class="mdc-slider__input" type="range" min="0" max="100" value="50" name="volume" aria-label="Continuous slider demo">
|
96 | <div class="mdc-slider__track">
|
97 | <div class="mdc-slider__track--inactive"></div>
|
98 | <div class="mdc-slider__track--active">
|
99 | <div class="mdc-slider__track--active_fill"></div>
|
100 | </div>
|
101 | </div>
|
102 | <div class="mdc-slider__thumb">
|
103 | <div class="mdc-slider__thumb-knob"></div>
|
104 | </div>
|
105 | </div>
|
106 | ```
|
107 |
|
108 | #### Continuous range slider
|
109 |
|
110 | <img src="images/continuous-range-slider.png" alt="Continuous range slider with values of 30 and 70">
|
111 |
|
112 | ```html
|
113 | <div class="mdc-slider mdc-slider--range">
|
114 | <input class="mdc-slider__input" type="range" min="0" max="70" value="30" name="rangeStart" aria-label="Continuous range slider demo">
|
115 | <input class="mdc-slider__input" type="range" min="30" max="100" value="70" name="rangeEnd" aria-label="Continuous range slider demo">
|
116 | <div class="mdc-slider__track">
|
117 | <div class="mdc-slider__track--inactive"></div>
|
118 | <div class="mdc-slider__track--active">
|
119 | <div class="mdc-slider__track--active_fill"></div>
|
120 | </div>
|
121 | </div>
|
122 | <div class="mdc-slider__thumb">
|
123 | <div class="mdc-slider__thumb-knob"></div>
|
124 | </div>
|
125 | <div class="mdc-slider__thumb">
|
126 | <div class="mdc-slider__thumb-knob"></div>
|
127 | </div>
|
128 | </div>
|
129 | ```
|
130 |
|
131 | ### Discrete slider
|
132 |
|
133 | Discrete sliders display a numeric value label upon pressing the thumb, which
|
134 | allows a user to select an exact value.
|
135 |
|
136 | <img src="images/discrete-slider.png" alt="Discrete slider with a value of 50">
|
137 |
|
138 | To create a discrete slider, add the following:
|
139 |
|
140 | * `mdc-slider--discrete` class on the root element.
|
141 | * Value indicator element (`mdc-slider__value-indicator-container`), as shown
|
142 | below.
|
143 |
|
144 | ```html
|
145 | <div class="mdc-slider mdc-slider--discrete">
|
146 | <input class="mdc-slider__input" type="range" min="0" max="100" value="50" name="volume" step="10" aria-label="Discrete slider demo">
|
147 | <div class="mdc-slider__track">
|
148 | <div class="mdc-slider__track--inactive"></div>
|
149 | <div class="mdc-slider__track--active">
|
150 | <div class="mdc-slider__track--active_fill"></div>
|
151 | </div>
|
152 | </div>
|
153 | <div class="mdc-slider__thumb">
|
154 | <div class="mdc-slider__value-indicator-container" aria-hidden="true">
|
155 | <div class="mdc-slider__value-indicator">
|
156 | <span class="mdc-slider__value-indicator-text">
|
157 | 50
|
158 | </span>
|
159 | </div>
|
160 | </div>
|
161 | <div class="mdc-slider__thumb-knob"></div>
|
162 | </div>
|
163 | </div>
|
164 | ```
|
165 |
|
166 | #### Discrete slider with tick marks
|
167 |
|
168 | Discrete sliders can optionally display tick marks. Tick marks represent
|
169 | predetermined values to which the user can move the slider.
|
170 |
|
171 | <img src="images/discrete-slider-tick-marks.png" alt="Discrete slider (with tick marks), with a value of 50">
|
172 |
|
173 | To add tick marks to a discrete slider, add the following:
|
174 |
|
175 | * `mdc-slider--tick-marks` class on the root element
|
176 | * `mdc-slider__tick-marks` element as a child of the `mdc-slider__track`
|
177 | element
|
178 | * `mdc-slider__tick-mark--active` and `mdc-slider__tick-mark--inactive`
|
179 | elements as children of the `mdc-slider__tick-marks` element
|
180 |
|
181 | ```html
|
182 | <div class="mdc-slider mdc-slider--discrete mdc-slider--tick-marks">
|
183 | <input class="mdc-slider__input" type="range" min="0" max="100" value="50" name="volume" step="10" aria-label="Discrete slider with tick marks demo">
|
184 | <div class="mdc-slider__track">
|
185 | <div class="mdc-slider__track--inactive"></div>
|
186 | <div class="mdc-slider__track--active">
|
187 | <div class="mdc-slider__track--active_fill"></div>
|
188 | </div>
|
189 | <div class="mdc-slider__tick-marks">
|
190 | <div class="mdc-slider__tick-mark--active"></div>
|
191 | <div class="mdc-slider__tick-mark--active"></div>
|
192 | <div class="mdc-slider__tick-mark--active"></div>
|
193 | <div class="mdc-slider__tick-mark--active"></div>
|
194 | <div class="mdc-slider__tick-mark--active"></div>
|
195 | <div class="mdc-slider__tick-mark--active"></div>
|
196 | <div class="mdc-slider__tick-mark--inactive"></div>
|
197 | <div class="mdc-slider__tick-mark--inactive"></div>
|
198 | <div class="mdc-slider__tick-mark--inactive"></div>
|
199 | <div class="mdc-slider__tick-mark--inactive"></div>
|
200 | <div class="mdc-slider__tick-mark--inactive"></div>
|
201 | </div>
|
202 | </div>
|
203 | <div class="mdc-slider__thumb">
|
204 | <div class="mdc-slider__value-indicator-container" aria-hidden="true">
|
205 | <div class="mdc-slider__value-indicator">
|
206 | <span class="mdc-slider__value-indicator-text">
|
207 | 50
|
208 | </span>
|
209 | </div>
|
210 | </div>
|
211 | <div class="mdc-slider__thumb-knob"></div>
|
212 | </div>
|
213 | </div>
|
214 | ```
|
215 |
|
216 | #### Discrete range slider
|
217 |
|
218 | ```html
|
219 | <div class="mdc-slider mdc-slider--range mdc-slider--discrete">
|
220 | <input class="mdc-slider__input" type="range" min="0" max="50" value="20" step="10" name="rangeStart" aria-label="Discrete range slider demo">
|
221 | <input class="mdc-slider__input" type="range" min="20" max="100" value="50" step="10" name="rangeEnd" aria-label="Discrete range slider demo">
|
222 | <div class="mdc-slider__track">
|
223 | <div class="mdc-slider__track--inactive"></div>
|
224 | <div class="mdc-slider__track--active">
|
225 | <div class="mdc-slider__track--active_fill"></div>
|
226 | </div>
|
227 | </div>
|
228 | <div class="mdc-slider__thumb">
|
229 | <div class="mdc-slider__value-indicator-container" aria-hidden="true">
|
230 | <div class="mdc-slider__value-indicator">
|
231 | <span class="mdc-slider__value-indicator-text">
|
232 | 20
|
233 | </span>
|
234 | </div>
|
235 | </div>
|
236 | <div class="mdc-slider__thumb-knob"></div>
|
237 | </div>
|
238 | <div class="mdc-slider__thumb">
|
239 | <div class="mdc-slider__value-indicator-container" aria-hidden="true">
|
240 | <div class="mdc-slider__value-indicator">
|
241 | <span class="mdc-slider__value-indicator-text">
|
242 | 50
|
243 | </span>
|
244 | </div>
|
245 | </div>
|
246 | <div class="mdc-slider__thumb-knob"></div>
|
247 | </div>
|
248 | </div>
|
249 | ```
|
250 |
|
251 | ## Other variants
|
252 |
|
253 | ### Disabled slider
|
254 |
|
255 | To disable a slider, add the following:
|
256 |
|
257 | * `mdc-slider--disabled` class on the root element
|
258 | * `disabled` attribute on the input element
|
259 |
|
260 | ```html
|
261 | <div class="mdc-slider mdc-slider--disabled">
|
262 | <input class="mdc-slider__input" type="range" min="0" max="100" value="50" step="10" disabled name="volume" aria-label="Disabled slider demo">
|
263 | <div class="mdc-slider__track">
|
264 | <div class="mdc-slider__track--inactive"></div>
|
265 | <div class="mdc-slider__track--active">
|
266 | <div class="mdc-slider__track--active_fill"></div>
|
267 | </div>
|
268 | </div>
|
269 | <div class="mdc-slider__thumb">
|
270 | <div class="mdc-slider__thumb-knob"></div>
|
271 | </div>
|
272 | </div>
|
273 | ```
|
274 |
|
275 | ## Additional information
|
276 |
|
277 | ### Initialization with custom ranges and values
|
278 |
|
279 | When `MDCSlider` is initialized, it reads the input element's `min`,
|
280 | `max`, and `value` attributes if present, using them to set
|
281 | the component's internal `min`, `max`, and `value` properties.
|
282 |
|
283 | Use these attributes to initialize the slider with a custom range and values,
|
284 | as shown below:
|
285 |
|
286 | ```html
|
287 | <div class="mdc-slider">
|
288 | <input class="mdc-slider__input" aria-label="Slider demo" min="0" max="100" value="75">
|
289 | <!-- ... -->
|
290 | </div>
|
291 | ```
|
292 |
|
293 | ### Setting slider position before component initialization
|
294 |
|
295 | When `MDCSlider` is initialized, it updates the slider track and thumb
|
296 | positions based on the internal value(s). To set the correct track and thumb
|
297 | positions before component initialization, mark up the DOM as follows:
|
298 |
|
299 | - Calculate `rangePercentDecimal`, the active track range as a percentage of
|
300 | the entire track, i.e. `(valueEnd - valueStart) / (max - min)`.
|
301 | Set `transform:scaleX(<rangePercentDecimal>)` as an inline style on the
|
302 | `mdc-slider__track--active_fill` element.
|
303 | - Calculate `thumbEndPercent`, the initial position of the end thumb as a
|
304 | percentage of the entire track. Set `left:calc(<thumbEndPercent>% - 24px)`
|
305 | as an inline style on the end thumb (`mdc-slider__thumb`) element
|
306 | (or `right` for RTL layouts).
|
307 | - *[Range sliders only]* Calculate `thumbStartPercent`, the initial position
|
308 | of the start thumb as a percentage of the entire track. Set
|
309 | `left:calc(<thumbStartPercent>% - 24px)` as an inline style on the
|
310 | start thumb (`mdc-slider__thumb`) element (or `right` for RTL layouts).
|
311 | - *[Range sliders only]* Using the previously calculated `thumbStartPercent`,
|
312 | set `left:<thumbStartPercent>%` as an inline style on the
|
313 | `mdc-slider__track--active_fill` element (or `right` for RTL layouts).
|
314 |
|
315 | Additionally, the MDCSlider component should be initialized with
|
316 | `skipInitialUIUpdate` set to true.
|
317 |
|
318 | #### Range slider example
|
319 |
|
320 | This is an example of a range slider with internal values of
|
321 | `[min, max] = [0, 100]` and `[start, end] = [30, 70]`.
|
322 |
|
323 | ```html
|
324 | <div class="mdc-slider mdc-slider--range">
|
325 | <input class="mdc-slider__input" type="range" min="0" max="70" value="30" name="rangeStart" aria-label="Range slider demo">
|
326 | <input class="mdc-slider__input" type="range" min="30" max="100" value="70" name="rangeEnd" aria-label="Range slider demo">
|
327 | <div class="mdc-slider__track">
|
328 | <div class="mdc-slider__track--inactive"></div>
|
329 | <div class="mdc-slider__track--active">
|
330 | <div class="mdc-slider__track--active_fill"
|
331 | style="transform:scaleX(.4); left:30%"></div>
|
332 | </div>
|
333 | </div>
|
334 | <div class="mdc-slider__thumb" style="left:calc(30%-24px)">
|
335 | <div class="mdc-slider__thumb-knob"></div>
|
336 | </div>
|
337 | <div class="mdc-slider__thumb" style="left:calc(70%-24px)">
|
338 | <div class="mdc-slider__thumb-knob"></div>
|
339 | </div>
|
340 | </div>
|
341 | ```
|
342 |
|
343 | ## API
|
344 |
|
345 | ### Sass mixins
|
346 |
|
347 | Mixin | Description
|
348 | --- | ---
|
349 | `track-active-color($color)` | Sets the color of the active track.
|
350 | `track-inactive-color($color, $opacity)` | Sets the color and opacity of the inactive track.
|
351 | `thumb-color($color)` | Sets the color of the thumb.
|
352 | `thumb-ripple-color($color)` | Sets the color of the thumb ripple.
|
353 | `tick-mark-active-color($color)` | Sets the color of tick marks on the active track.
|
354 | `tick-mark-inactive-color($color)` | Sets the color of tick marks on the inactive track.
|
355 | `value-indicator-color($color, $opaicty)` | Sets the color and opacity of the value indicator.
|
356 | `value-indicator-text-color($color, $opaicty)` | Sets the color of the value indicator text.
|
357 |
|
358 | ### `MDCSlider` events
|
359 |
|
360 | Event name | `event.detail` | Description
|
361 | --- | --- | ---
|
362 | `MDCSlider:change` | `MDCSliderChangeEventDetail` | Emitted when a value has been changed and committed from a user event. Mirrors the native `change` event: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
|
363 | `MDCSlider:input` | `MDCSliderChangeEventDetail` | Emitted when a value has been changed from a user event. Mirrors the native `input` event: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
|
364 |
|
365 | ### `MDCSlider` methods
|
366 |
|
367 | Method Signature | Description
|
368 | --- | ---
|
369 | `getValueStart() => number` | Gets the value of the start thumb (only applicable for range sliders).
|
370 | `setValueStart(valueStart: number) => void` | Sets the value of the start thumb (only applicable for range sliders).
|
371 | `getValue() => number` | Gets the value of the thumb (for single point sliders), or the end thumb (for range sliders).
|
372 | `setValue(value: number) => void` | Sets the value of the thumb (for single point sliders), or the end thumb (for range sliders).
|
373 | `getDisabled() => boolean` | Gets the disabled state of the slider.
|
374 | `setDisabled(disabled: boolean) => void` | Sets the disabled state of the slider.
|
375 | `setValueToAriaValueTextFn((mapFn: ((value: number) => string) \| null) => void` | Sets a function that maps the slider value to value of the `aria-valuetext` attribute on the thumb element. If not set, the `aria-valuetext` attribute is unchanged when the value changes.
|
376 |
|
377 | ### Usage within frameworks
|
378 |
|
379 | If you are using a JavaScript framework such as React or Angular, you can create a slider for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).
|
380 |
|
381 | See [MDCSliderAdapter](./adapter.ts) and [MDCSliderFoundation](./foundation.ts) for up-to-date code documentation of slider foundation API's.
|