Range Sliders

HTML/CSS Available
Web Component Unavailable
Last Updated
2.2.0

Range Sliders select a numeric value, or range of values, by moving a handle, or set of handles, along a bar.

Variations

Single Selection

Use when soliciting a single numeric value.

With Input

Years

<div class="mds-range-slider__group">
    <div class="mds-range-slider__input-wrapper">
        <label class="mds-form__label" for="slider_number_field_1">
            Years
        </label>
        <input class="mds-form__input mds-range-slider__input" type="number" id="slider_number_field_1" min="0" max="100">
    </div>
    <div class="mds-range-slider__wrapper">
        <div id="slider_input" class="mds-range-slider" role="slider" aria-orientation="horizontal" aria-valuemin="0.0" aria-valuemax="100.0" aria-valuenow="20.0" aria-valuetext="20">
            <!-- This markup is dynamically created by the noUiSlider JS Library -->
        </div>
    </div>
</div>

Disabled

Years

<div class="mds-range-slider__group">
    <div class="mds-range-slider__input-wrapper">
        <label class="mds-form__label" for="slider_number_field_2">
            Years
        </label>
        <input class="mds-form__input mds-range-slider__input" type="number" id="slider_number_field_2" min="0" max="100" disabled>
    </div>
    <div class="mds-range-slider__wrapper">
        <div id="slider_input_disabled" disabled class="mds-range-slider" role="slider" aria-orientation="horizontal" aria-valuemin="0.0" aria-valuemax="100.0" aria-valuenow="20.0" aria-valuetext="20">
            <!-- This markup is dynamically created by the noUiSlider JS Library -->
        </div>
    </div>
</div>

Add the disabled attribute to a div with a unique ID, i.e., <div id="[mySliderDivId]" disabled>.
Add the disabled attribute to all binded Form Text Boxes, i.e., <input id="[myInputId]" disabled>.

Range Selection

Use when soliciting a range between two numeric values.

With Inputs

Minimum Value

Maximum Value

<div class="mds-range-slider__group--min-max">
    <div class="mds-range-slider__input-wrapper">
        <label class="mds-form__label" for="slider_two_number_field_min_1">
            Minimum Value
        </label>
        <input class="mds-form__input mds-range-slider__input mds-range-slider__input--min" type="number" id="slider_two_number_field_min_1" min="0" max="100">
    </div>
    <div class="mds-range-slider__wrapper">
        <div id="slider_two_with_input" class="mds-range-slider">
            <!-- This markup is dynamically created by the noUiSlider JS Library -->
        </div>
    </div>
    <div class="mds-range-slider__input-wrapper">
        <label class="mds-form__label" for="slider_two_number_field_max_1">
            Maximum Value
        </label>
        <input class="mds-form__input mds-range-slider__input mds-range-slider__input--max" type="number" id="slider_two_number_field_max_1" min="0" max="100">
    </div>
</div>

By default, Form Text Boxes should display the top and bottom range of slider values.

Disabled

Minimum Value

Maximum Value

<div class="mds-range-slider__group--min-max">
    <div class="mds-range-slider__input-wrapper">
        <label class="mds-form__label" for="slider_two_number_field_min_2">
            Minimum Value
        </label>
        <input class="mds-form__input mds-range-slider__input mds-range-slider__input--min" type="number" id="slider_two_number_field_min_2" min="0" max="100" disabled>
    </div>
    <div class="mds-range-slider__wrapper">
        <div id="slider_two_with_input_disabled" disabled class="mds-range-slider">
            <!-- This markup is dynamically created by the noUiSlider JS Library -->
        </div>
    </div>
    <div class="mds-range-slider__input-wrapper">
        <label class="mds-form__label" for="slider_two_number_field_max_2">
            Maximum Value
        </label>
        <input class="mds-form__input mds-range-slider__input mds-range-slider__input--max" type="number" id="slider_two_number_field_max_2" min="0" max="100" disabled>
    </div>
</div>

Add the disabled attribute to a div with a unique ID, i.e., <div id="[mySliderDivId]" disabled>.
Add the disabled attribute to all binded Form Text Boxes, i.e., <input id="[myInputId]" disabled>.

Guidelines

Use When

Encouraging user exploration when setting a value or range of values, especially when that value has an immediate effect on a data visualization.

Don’t Use When

Gathering information in a form, i.e., “Age” or “Salary”. Instead, use a Form Text Box.

Visual Language

Always include the Form Text Box(es) when using a slider to ensure the component is controllable via keyboard.
Position the slider’s Form Text Box(es) to meet the requirements of your product.
A range slider will fill out 100% of the width of its container. Do not set an explicit width on the <div id="[mySliderDivId]"></div> element as it will break the rendering. Any widths to control the range slider must be set on its parent element.

Behaviors

Adjust a slider’s value(s) by clicking and dragging its handle(s), or by clicking anywhere on its bar.
Hovering over an active slider’s handle will change the default cursor to the grab cursor; clicking will change to the grabbing cursor.
The System's sliders are built using noUiSlider. For a full breakdown of behaviors and configurations, please refer to the official noUiSlider documentation.

Accessibility

Always include a Form Text Box with the slider.
Follow guidelines for Form Text Boxes.
Include correct aria and role attributes for the sliders. When using the noUiSlider library these attributes are added automatically. See Mozilla’s slider accessibility documentation for details.
Always include min and max attributes for Form Text Boxes.
Ensure slider values can be increased and decreased using keyboard arrow keys. See Mozilla’s slider accessibility documentation for recommendations.
Always include label elements with slider input fields. If no labels are desired, use the mds-doc-screenreader-only class to visually hide the labels while preserving accessibility.

Code Reference

CSS Class References

Class	Applies to	Outcome
`mds-range-slider__wrapper`	`<div>` and is the direct parent of `<div id="[mySliderId]">`	Handles width and positioning of the slider bar.
`mds-range-slider__input-wrapper`	`<div>` and is the direct parent of `<div id="[myInputId]">`	Handles width and positioning of the `inputs`.
`mds-range-slider--hidden`	`<div id="[mySliderId]">`	Hides the slider bar.
`mds-range-slider__input`	`<input id="[myInputId]">`	Sets a `min-width` value on the `input` element to ensure it will always allow for two digits.

JavaScript Considerations

The System’s range sliders depend on the noUiSlider (^10.1.0) third-party JavaScript library, offered via the MDS Node Package. If you are not using MDS through our Node package, you can download noUiSlider separately.

You can review the noUiSlider documentation to see what options are available.

Initialization

When initializing a range slider, you must use noUiSlider's cssClasses and cssPrefix options to apply the correct MDS CSS styles.

Copy this code in to your codebase to create the mdsRangeSliderClassOverrides variable, which maps all noUiSlider styles to relevant MDS BEM classes:

// Class overrides to follow BEM conventions in MDS
const mdsRangeSliderClassOverrides = {
    'target': '__target',
    'base': '__base',
    'origin': '__origin',
    'handle': '__handle',
    'handleLower': '__handle--lower',
    'handleUpper': '__handle--upper',
    'horizontal': '--horizontal',
    'vertical': '--vertical',
    'background': '__background',
    'connect': '__connect',
    'ltr': '--ltr',
    'rtl': '--rtl',
    'draggable': '--draggable',
    'drag': '--state-drag',
    'tap': '--state-tap',
    'active': '--active',
    'tooltip': '__tooltip',
    'pips': '__pips',
    'pipsHorizontal': '__pips--horizontal',
    'pipsVertical': '__pips--vertical',
    'marker': '__marker',
    'markerHorizontal': '__marker--horizontal',
    'markerVertical': '__marker--vertical',
    'markerNormal': '__marker--normal',
    'markerLarge': '__marker--large',
    'markerSub': '__marker--sub',
    'value': '__value',
    'valueHorizontal': '__value--horizontal',
    'valueVertical': '__value-vertical',
    'valueNormal': '__value-normal',
    'valueLarge': '__value-large',
    'valueSub': '__value-sub'
};

When initializing a range slider, use the cssPrefix and cssClasses options to apply MDS styles:

// Initalize a range slider with class overrides
const mySlider = document.getElementById('mySliderId');
noUiSlider.create(mySlider, {
    ...
    cssPrefix: 'mds-range-slider',
    cssClasses: mdsRangeSliderClassOverrides,
    ...
});

Link Template