Rangeslider Widgetversion added: 1.3
Description: Creates a rangeslider widget
Range Slider
The rangeslider widget can be considered as a double handle slider. To add a rangeslider widget to your page, use two standard inputs with the type="range"
attribute, and put them inside a <div>
container. The input values are used to configure the starting position of the handles and the values are populated in the corresponding text inputs (the first one at the beginning of the rangeslider, and the second one at the end). Specify min
and max
attribute values to set the rangeslider's range. If you want to constrain inputs to specific increments, add the step
attribute. Set the value
attribute on each input to define their initial value. The framework will parse these attributes to configure the rangeslider widget.
As you drag the rangeslider's handles, the framework will update the native input values (and vice-versa) so they are always in sync; this ensures that the values are submitted with the form.
Set the for
attribute of the labels
to match the ids
of the inputs
so they are semantically associated. It's possible to accessibly hide the labels if they're not desired in the page layout, but we require that they are 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 the data-role="none"
attribute to the inputs.
In this example, the acceptable range is 0-100.
1
2
3
4
5
6
|
|
The default rangeslider with these settings is displayed like this:
Step increment
To force the range 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 0.1 and the maximum value is 10.
In this example, the acceptable range is 0-100.
1
2
3
4
5
6
|
|
This will produce an input that snaps to increments of 0.1. 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
By default, there is a highlight fill on the track between the two slider handles. To remove it, add the data-highlight="false"
attribute to the input. The fill uses the active state swatch.
1
2
3
4
5
6
|
|
Theming the slider
To set the theme swatch for the rangeslider, add a data-theme
attribute to the inputs
which will apply the theme to the inputs, handles 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
5
6
|
|
This will produce a themed rangeslider:
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
6
|
|
This will produce a rangeslider and its corresponding inputs that are not as tall as the standard version. The inputs also have a smaller text size.
Field containers
Optionally wrap the rangeslider 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. Use the ui-field-contain
class instead.
1
2
3
4
5
6
7
8
|
|
The rangeslider 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 rangeslider plugin
This plugin will auto initialize on any page that contains a div
with the data-role="rangeslider"
attribute. However, if needed you can directly call the rangeslider plugin on any selector, just like any jQuery plugin:
1
|
|
Options
defaults
false
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"
.
Initialize the rangeslider with the defaults
option specified:
1
2
3
|
|
Get or set the defaults
option, after initialization:
1
2
3
4
5
|
|
disabled
false
true
.
This option is also exposed as a data attribute: data-disabled="true"
.
Initialize the rangeslider with the disabled
option specified:
1
2
3
|
|
Get or set the disabled
option, after initialization:
1
2
3
4
5
|
|
highlight
true
This option is also exposed as a data attribute: data-highlight="false"
.
Initialize the rangeslider with the highlight
option specified:
1
2
3
|
|
Get or set the highlight
option, after initialization:
1
2
3
4
5
|
|
initSelector
See below
The default initSelector
for the rangeslider widget is:
1
|
|
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
|
|
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 rangeslider widgets on each of the resulting list of elements.
(version deprecated: 1.4.0)mini
null (false)
true
, this will display a more compact version of the rangeslider that uses less vertical height by applying the ui-mini
class to the outermost element of the rangeslider widget.
This option is also exposed as a data attribute: data-mini="true"
.
theme
null, inherited from parent
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Initialize the rangeslider with the theme
option specified:
1
2
3
|
|
Get or set the theme
option, after initialization:
1
2
3
4
5
|
|
trackTheme
null, inherited from parent
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"
.
Initialize the rangeslider with the trackTheme
option specified:
1
2
3
|
|
Get or set the trackTheme
option, after initialization:
1
2
3
4
5
|
|
Methods
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
1
|
|
disable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the disable method:
1
|
|
enable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the enable method:
1
|
|
option( optionName )Returns: Object
optionName
.-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
|
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )Returns: jQuery (plugin only)
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )Returns: jQuery (plugin only)
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
refresh()Returns: jQuery (plugin only)
If you manipulate a rangeslider via JavaScript, you must call the refresh method on it to update the visual styling.
- This method does not accept any arguments.
Invoke the refresh method:
1
|
|
Events
create( event, ui )Type: rangeslidercreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the rangeslider with the create callback specified:
1
2
3
|
|
Bind an event listener to the rangeslidercreate event:
1
|
|
normalize( event )Type: rangeslidernormalize
-
eventType: Event
Note: The ui
object is empty but included for consistency with other events.
Initialize the rangeslider with the normalize callback specified:
1
2
3
|
|
Bind an event listener to the rangeslidernormalize event:
1
|
|
Example:
A basic example of a rangeslider.
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
|
|