Slider Widget


Slider Widgetversion added: 1.0

Description: Creates a slider widget

QuickNavExamples

Events

Slider

To add a slider widget to your page, use a standard input with the type="range" attribute. The input's value is used to configure the starting position of the handle and the value is populated in the text input. Specify min and max attribute values to set the slider's range. If you want to constrain input to specific increments, add the step attribute. Set the value attribute to define the initial value. The framework will parse these attributes to configure the slider widget.

As you drag the slider's handle, the framework will update the native input's value (and vice-versa) so they are always in sync; this ensures that the value is submitted with the form.

Set the for attribute of the label to match the id of the input so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.

The framework will find all input elements with a type="range" and automatically enhance them into a slider with an accompanying input without any need to apply a data-role attribute. To prevent the automatic enhancement of this input into a slider, add data-role="none" attribute to the input.

In this example, the acceptable range is 0-100.

1
2
<label for="slider-1">Input slider:</label>
<input type="range" name="slider-1" id="slider-1" value="60" min="0" max="100">

The default slider with these settings is displayed like this:

Theming

The slider widget uses the jQuery Mobile CSS framework to style its look and feel. If slider specific styling is needed, the following CSS class names can be used for overrides or as keys for the classes option:

  • ui-slider: The outermost container for slider.
    • ui-slider-popup: Tooltip popup element in case data-popup-enabled is true
    • ui-slider-input: Input element of slider
    • ui-slider-track: Slider's track
      • ui-slider-handle: Handle of slider's track

Step increment

To force the slider to snap to a specific increment, add the step attribute to the input. By default, the step is 1, but in this example, the step is 10 and the maximum value is 500.

In this example, the acceptable range is 0-100.

1
2
<label for="slider-1">Input slider:</label>
<input type="range" name="slider-1" id="slider-1" value="60" min="0" max="100" step="10">

This will produce an input that snaps to increments of 50. If a value is added to the input that isn't valid with the step increment, the value will be reset on blur to the closest step.

Fill highlight

To have a highlight fill on the track up to the slider handle position, add the data-highlight="true" attribute to the input. The fill uses active state swatch.

1
2
<label for="slider-fill">Input slider:</label>
<input type="range" name="slider-fill" id="slider-fill" value="60" min="0" max="100" data-highlight="true">

Mini version

For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.

1
2
<label for="slider-mini">Input slider:</label>
<input type="range" name="slider-mini" id="slider-mini" value="25" min="0" max="100" data-highlight="true" data-mini="true">

This will produce a slider and its corresponding input that are not as tall as the standard version. The input also has a smaller text size.

Field containers

Optionally wrap the slider markup in a container with class ui-field-contain to help visually group it in a longer form. In this example, the step attribute is omitted to allow any whole number value to be selected.

Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.

1
2
3
4
<div class="ui-field-contain">
<label for="slider-2">Input slider:</label>
<input type="range" name="slider-2" id="slider-2" value="25" min="0" max="100">
</div>

The slider is now displayed like this:

Sliders also respond to key commands. Right Arrow, Up Arrow and Page Up keys increase the value; Left Arrow, Down Arrow and Page Down keys decrease it. To move the slider to its minimum or maximum value, use the Home or End key, respectively.

Calling the slider plugin

This plugin will auto initialize on any page that contains a text input with the type="range" attribute. However, if needed you can directly call the slider plugin on any selector, just like any jQuery plugin:

1
$( "input" ).slider();

Theming the slider

To set the theme swatch for the slider, add a data-theme attribute to the input which will apply the theme to both the input, handle and track. The track swatch can be set separately by adding the data-track-theme attribute to apply the down state version of the selected button swatch.

1
2
3
4
<div class="ui-field-contain">
<label for="slider-3">Input slider:</label>
<input type="range" name="slider-3" id="slider-3" value="25" min="0" max="100" data-theme="b" data-track-theme="a">
</div>

This will produce a themed slider:

Flip Toggle Switch

Note: The flip toggle switch feature is deprecated as of jQuery Mobile 1.4.0. Use the Flipswitch widget instead.

A binary "flip" switch is a common UI element on mobile devices that is used for binary on/off or true/false data input. You can either drag the flip handle like a slider or tap one side of the switch.

To create a flip toggle, start with a select with two options. The first option will be styled as the "off" state switch and the second will be styled as the "on" state so write your options accordingly.

Set the for attribute of the label to match the id of the input so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.

1
2
3
4
5
<label for="flip-1">Flip switch:</label>
<select name="flip-1" id="flip-1" data-role="slider">
<option value="off">Off</option>
<option value="on">On</option>
</select>

This will produce a basic flip toggle switch input. The default styles set the width of the switch to 100% of the parent container and stack the label on a separate line.

Longer Labels

The control is proportionally scaled, so to use longer labels one can just add a line of CSS setting the switch to the desired width. For example, given the following markup:

1
2
3
4
5
6
7
<div class="containing-element">
<label for="flip-min">Flip switch:</label>
<select name="flip-min" id="flip-min" data-role="slider">
<option value="off">Switch Off</option>
<option value="on">Switch On</option>
</select>
</div>

.containing-element .ui-slider-switch { width: 9em } will produce:

As some default styles hinge on fieldcontains, note that you may have to ensure that custom styles apply to switches within fieldcontains by using .ui-field-contain div.ui-slider-switch { width: […]; }.

Mini version

For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.

1
2
3
4
5
<label for="flip-mini">Flip switch:</label>
<select name="flip-mini" id="flip-mini" data-role="slider" data-mini="true">
<option value="off">Off</option>
<option value="on">On</option>
</select>

This will produce a flip switch that is not as tall as the standard version and has a smaller text size.

Field containers

Optionally wrap the switch markup in a container with class ui-field-contain to help visually group it in a longer form. In this example, the step attribute is omitted to allow any whole number value to be selected.

Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.

1
2
3
4
5
6
7
<div class="ui-field-contain">
<label for="flip-2">Flip switch:</label>
<select name="flip-2" id="flip-2" data-role="slider" data-mini="true">
<option value="off">Off</option>
<option value="on">On</option>
</select>
</div>

The flip toggle switch is now displayed like this:

Theming the flip switch

Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the data-theme attribute on the select and specify a swatch letter.

1
2
3
4
5
6
7
<div class="ui-field-contain">
<label for="flip-3">Flip switch:</label>
<select name="flip-3" id="flip-3" data-role="slider" data-theme="b">
<option value="no">No</option>
<option value="yes">Yes</option>
</select>
</div>

This results in a switch with the swatch "b" colors for the handle. Note that the lefthand "on" state gets the active state color.

Here is a swatch "a" variation:

It is also possible to theme the track of the flip switch by adding the data-track-theme attribute and specifying the chosen swatch letter on the select.

Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:

1
2
3
4
5
6
7
<div class="ui-field-contain">
<label for="flip-5">Flip switch:</label>
<select name="flip-5" id="flip-5" data-role="slider" data-theme="a" data-track-theme="b">
<option value="no">No</option>
<option value="yes">Yes</option>
</select>
</div>

Calling the switch plugin

This plugin will auto initialize on any page that contains a text input with the type="slider" attribute. However, if needed you can directly call the slider plugin on any selector, just like any jQuery plugin:

1
$( "input" ).slider();

Theming the flip switch

Like all form elements, this widget will automatically inherit the theme from its parent container. To choose a specific theme color swatch, specify the data-theme attribute on the select and specify a swatch letter.

1
2
3
4
5
6
7
<div class="ui-field-contain">
<label for="flip-3">Flip switch:</label>
<select name="flip-3" id="flip-3" data-role="slider" data-theme="a">
<option value="no">No</option>
<option value="yes">Yes</option>
</select>
</div>

This results in a switch with the swatch "a" colors for the handle. Note that the lefthand "on" state gets the active state color.

It is also possible to theme the track of the flip switch by adding the data-track-theme attribute and specifying the chosen swatch letter on the select.

Here's an example of a flip switch with the swatch "a" applied to the track and swatch "c" applied to the handle:

1
2
3
4
5
6
7
<div class="ui-field-contain">
<label for="flip-5">Flip switch:</label>
<select name="flip-5" id="flip-5" data-role="slider" data-theme="a" data-track-theme="b">
<option value="no">No</option>
<option value="yes">Yes</option>
</select>
</div>

Options

classes 

Type: Object
Default:
{
"ui-slider-track": "ui-shadow-inset ui-corner-all",
"ui-slider-input": "ui-shadow-inset ui-corner-all"
}

Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes option.

Code examples:

Initialize the slider with the classes option specified, changing the theming for the ui-slider class:

1
2
3
4
5
$( ".selector" ).slider({
classes: {
"ui-slider": "highlight"
}
});

Get or set a property of the classes option, after initialization, here reading and changing the theming for the ui-slider class:

1
2
3
4
5
// Getter
var themeClass = $( ".selector" ).slider( "option", "classes.ui-slider" );
// Setter
$( ".selector" ).slider( "option", "classes.ui-slider", "highlight" );

defaults 

Type: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the slider with the defaults option specified:

1
2
3
$( ".selector" ).slider({
defaults: true
});

Get or set the defaults option, after initialization:

1
2
3
4
5
// Getter
var defaults = $( ".selector" ).slider( "option", "defaults" );
// Setter
$( ".selector" ).slider( "option", "defaults", true );

disabled 

Type: Boolean
Default: false
Disables the slider if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the slider with the disabled option specified:

1
2
3
$( ".selector" ).slider({
disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
// Getter
var disabled = $( ".selector" ).slider( "option", "disabled" );
// Setter
$( ".selector" ).slider( "option", "disabled", true );

highlight 

Type: Boolean
Default: false
Sets an active state fill on the track from the left edge to the slider handle when set to "true".
Code examples:

Initialize the slider with the highlight option specified:

1
2
3
$( ".selector" ).slider({
highlight: true
});

Get or set the highlight option, after initialization:

1
2
3
4
5
// Getter
var highlight = $( ".selector" ).slider( "option", "highlight" );
// Setter
$( ".selector" ).slider( "option", "highlight", true );

initSelector 

Type: Selector
Default: See below

The default initSelector for the slider widget is:

1
"input[type='range'], :jqmData(type='range'), :jqmData(role='slider')"

Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit event and overwriting the initSelector on the prototype:

1
2
3
$( document ).on( "mobileinit", function() {
$.mobile.slider.prototype.initSelector = "div.custom";
});

Note: Remember to attach the mobileinit handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.

The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates slider widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

mini 

Type: Boolean
Default: null (false)
If set to true, this will display a more compact version of the slider that uses less vertical height by applying the ui-mini class to the outermost element of the slider widget.

Note: mini option is deprecated in 1.5 and will be removed in 1.6

This option is also exposed as a data attribute: data-mini="true".

theme 

Type: String
Default: null, inherited from parent
Sets the color scheme (swatch) for the slider widget. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

This option is also exposed as a data attribute: data-theme="b".

Code examples:

Initialize the slider with the theme option specified:

1
2
3
$( ".selector" ).slider({
theme: "b"
});

Get or set the theme option, after initialization:

1
2
3
4
5
// Getter
var theme = $( ".selector" ).slider( "option", "theme" );
// Setter
$( ".selector" ).slider( "option", "theme", "b" );

trackTheme 

Type: String
Default: null, inherited from parent
Sets the color scheme (swatch) for the slider's track, specifically. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

This option can be overridden in the markup by assigning a data attribute to the input, e.g. data-track-theme="a".

Code examples:

Initialize the slider with the trackTheme option specified:

1
2
3
$( ".selector" ).slider({
trackTheme: "a"
});

Get or set the trackTheme option, after initialization:

1
2
3
4
5
// Getter
var trackTheme = $( ".selector" ).slider( "option", "trackTheme" );
// Setter
$( ".selector" ).slider( "option", "trackTheme", "a" );

Methods

destroy()Returns: jQuery (plugin only)

Removes the slider functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
$( ".selector" ).slider( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the slider.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
$( ".selector" ).slider( "disable" );

enable()Returns: jQuery (plugin only)

Enables the slider.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
$( ".selector" ).slider( "enable" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
var isDisabled = $( ".selector" ).slider( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current slider options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
var options = $( ".selector" ).slider( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the slider option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
$( ".selector" ).slider( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the slider.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
$( ".selector" ).slider( "option", { disabled: true } );

refresh()Returns: jQuery (plugin only)

update the slider.

If you manipulate a slider via JavaScript, you must call the refresh method on it to update the visual styling.

  • This method does not accept any arguments.
Code examples:

Invoke the refresh method:

1
$( ".selector" ).slider( "refresh" );

Events

create( event, ui )Type: slidecreate

Triggered when the slider is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the slider with the create callback specified:

1
2
3
$( ".selector" ).slider({
create: function( event, ui ) {}
});

Bind an event listener to the slidecreate event:

1
$( ".selector" ).on( "slidecreate", function( event, ui ) {} );

start( event )Type: slidestart

triggered when there's an initial interaction with the slider. Includes drags and taps.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the slider with the start callback specified:

1
2
3
$( ".selector" ).slider({
start: function( event, ui ) {}
});

Bind an event listener to the slidestart event:

1
$( ".selector" ).on( "slidestart", function( event, ui ) {} );

stop( event )Type: slidestop

triggered at the end of an interaction with the slider. Includes drags and taps.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the slider with the stop callback specified:

1
2
3
$( ".selector" ).slider({
stop: function( event, ui ) {}
});

Bind an event listener to the slidestop event:

1
$( ".selector" ).on( "slidestop", function( event, ui ) {} );

Examples:

A basic example of a slider.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>slider demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.css">
<script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
<script src="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.js"></script>
</head>
<body>
<div data-role="header">
<h1>jQuery Mobile Example</h1>
</div>
<div role="main" class="ui-content">
<label for="slider-0">Input slider:</label>
<input type="range" name="slider-0" id="slider-0" value="60" min="0" max="100">
</div>
</body>
</html>

Demo:

A basic example of a flip toggle switch.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>slider demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.css">
<script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
<script src="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.js"></script>
</head>
<body>
<div data-role="page" id="page1">
<div data-role="header">
<h1>jQuery Mobile Example</h1>
</div>
<div role="main" class="ui-content">
<label for="flip-0">Select slider:</label>
<select name="flip-0" id="flip-0" data-role="slider">
<option value="off">Off</option>
<option value="on">On</option>
</select>
</div>
</div>
</body>
</html>

Demo: