jQRangeSlider - Documentation

Prerequisites

jQuery
jQuery UI Core
jQuery UI Widget
jQuery mousewheel plugin (optional)

jQRangeSlider is highly dependant on CSS. Be sure to include one of the provided stylesheets.

Basic slider

Info: If you use more than one type of slider, please report to the multiple sliders section.

<!DOCTYPE>
  <html>
  <head>
    <meta charset="utf-8"/>
    <title>example</title>
    <link rel="stylesheet" href="css/iThing.css" type="text/css" />
  </head>
  <body>

    <h1>Hello world</h1>
    <div id="slider"></div>

    <script src="jquery.js"></script>
    <script src="jquery-ui.custom.js"></script>
    <script src="jQRangeSlider-min.js"></script>
    <script>
    //<!--
      $("#slider").rangeSlider();
    //-->
    </script>
  </body>
</html>

Edit slider

Info: If you use more than one type of slider, please report to the multiple sliders section.

<!DOCTYPE>
  <html>
  <head>
    <meta charset="utf-8"/>
    <title>example</title>
    <link rel="stylesheet" href="css/iThing.css" type="text/css" />
  </head>
  <body>

    <h1>Hello world</h1>
    <div id="slider"></div>

    <script src="jquery.js"></script>
    <script src="jquery-ui.custom.js"></script>
    <script src="jQEditRangeSlider-min.js"></script>
    <script>
    //<!--
      $("#slider").editRangeSlider();
    //-->
    </script>
  </body>
</html>

Date slider

Info: If you use more than one type of slider, please report to the multiple sliders section.

<!DOCTYPE>
  <html>
  <head>
    <meta charset="utf-8"/>
    <title>example</title>
    <link rel="stylesheet" href="css/iThing.css" type="text/css" />
  </head>
  <body>

    <h1>Hello world</h1>
    <div id="slider"></div>

    <script src="jquery.js"></script>
    <script src="jquery-ui.custom.js"></script>
    <script src="jQDateRangeSlider-min.js"></script>
    <script>
    //<!--
      $("#slider").dateRangeSlider();
    //-->
    </script>
  </body>
</html>

Multiple sliders

If you are using multiple sliders on the same page, you need to use another javascript file: jQAllRangeSliders-min.js. This file contains all necessary javascript for creating all types of slider. As most part of the source code is common between different kind of sliders, it's a good practice to use this file instead of including multiple minified files.

<!DOCTYPE>
  <html>
  <head>
    <meta charset="utf-8"/>
    <title>example</title>
    <link rel="stylesheet" href="css/iThing.css" type="text/css" />
  </head>
  <body>

    <h1>Hello world</h1>
    <div id="slider"></div>
    <div id="dateSlider"></div>
    <div id="editSlider"></div>

    <script src="jquery.js"></script>
    <script src="jquery-ui.custom.js"></script>
    <script src="jQAllRangeSliders-min.js"></script>
    <script>
    //<!--
      $("#slider").rangeSlider();
      $("#dateSlider").dateRangeSlider();
      $("#editSlider").editRangeSlider();
    //-->
    </script>
  </body>
</html>

Get and set options

Options can be set in constructor or after initialization.

// Set option value in constructor
$("#slider").rangeSlider({
  bounds: {min: 0, max: 100}
});

// Change options after slider creation
$("#slider").rangeSlider("option", "bounds", {min: 10, max: 90});

// Get option value
var bounds = $("#slider").rangeSlider("option", "bounds");

// Set date option
$("#dateSlider").dateRangeSlider(
  "option",
  "bounds",
  {
    min: new Date(2012, 0, 1),
    max: new Date(2012, 11, 31)  
});

Warning: Date range sliders need to be initialized with date objects. Strings don't work.

Info: When creating a date object in javascript, month number starts from 0. Don't ask me why.

Arrows

The option arrows lets you remove scrolling arrows on both sides of the slider.

Info: By default, arrows are activated.

Basic slider (example above)

$("#arrowsExample").rangeSlider({arrows:false});

Edit slider

$("#arrowsExample").editRangeSlider({arrows:false});

Date slider

$("#arrowsExample").dateRangeSlider({arrows:false});

Bounds

The option bounds allows you to modify min and max values of the slider.

Basic slider (example above)

$("#boundsExample").rangeSlider({bounds:{min: 10, max: 90}});

Edit slider

$("#boundsExample").editRangeSlider({bounds:{min: 10, max: 90}});

Date slider

$("#boundsExample").dateRangeSlider({
  bounds:{
    min: new Date(2012, 0, 1),
    max: new Date(2012, 11, 31)
  }});

Default values

The option defaultValues lets you specify values selected by default on construction.

Warning: This option can only be used in constructor. Once the slider has been constructed, it has no effect.

Basic slider (example above)

$("#defaultValuesExample").rangeSlider(defaultValues:{min: 10, max: 90}});

Edit slider

$("#defaultValuesExample").editRangeSlider({defaultValues:{min: 10, max: 90}});

Date slider

$("#defaultValuesExample").dateRangeSlider({
  defaultValues:{
    min: new Date(2012, 0, 1),
    max: new Date(2012, 11, 31)
  }});

Delay out

Option delayOut lets you specify the duration labels are shown after the user changed its values..

Warning: This option can only be used in conjunction with valueLabels: "change".

Basic slider (example above)

$("#delayExample").rangeSlider({
  valueLabels:"change",
  delayOut: 4000
});

Edit slider

$("#delayExample").editRangeSlider({
  valueLabels:"change",
  delayOut: 4000
});

Date slider

$("#delayExample").dateRangeSlider({
  valueLabels:"change",
  delayOut: 4000
});

Duration in/out

Option durationIn lets you specify the animation length when displaying value labels. Similarly, durationOut allows to customize the animation duration when hiding those labels.

Warning: This option can only be used in conjonction with valueLabels: "change".

Basic slider (example above)

$("#durationExample").rangeSlider({
  valueLabels:"change",
  durationIn: 1000,
  durationOut: 1000
});

Edit slider

$("#defaultValuesExample").editRangeSlider({
  valueLabels:"change",
  durationIn: 1000,
  durationOut: 1000
});

Date slider

$("#defaultValuesExample").dateRangeSlider({
  valueLabels:"change",
  durationIn: 1000,
  durationOut: 1000
});

Formatter

The option formatter lets you customize displayed label text.

Basic slider (example above)

$("#formatterExample").rangeSlider({
  formatter:function(val){
        var value = Math.round(val * 5) / 5,
          decimal = value - Math.round(val);

        return decimal == 0 ? value.toString() + ".0" : value.toString();
      }});
});

Edit slider

$("#formatterExample").editRangeSlider({
  formatter:function(val){
        var value = Math.round(val * 5) / 5,
          decimal = value - Math.round(val);

        return decimal == 0 ? value.toString() + ".0" : value.toString();
      }});
});

Date slider

$("#formatterExample").dateRangeSlider({
  formatter:function(val){
        var days = val.getDate(),
          month = val.getMonth() + 1,
          year = val.getFullYear();

        return days + "/" + month + "/" + year;
      }});
});

Range

The option range lets you specify minimum and/or maximum range length. For instance, let's consider you want the user to choose a range of dates during 2012. You can constraint people to choose at least 1 week during this period. Similarly, you also can constraint the user to choose 90 days at maximum.

When this option is activated, the slider constraints the user input. When minimum or maximum value is reached, the user cannot move an extremity further to shrink/enlarge the selected range.

Info: This option is deactivated by default

Basic slider (example above)

$("#rangeExample").rangeSlider({range: {min: 10, max: 40}});

Edit slider

$("#rangeExample").editRangeSlider({range: {min: 10, max: 40}});

Date slider

$("#rangeExample").dateRangeSlider({
  range:{
    min: {days: 2},
    max: {days: 7}
  }});

Minimum range only

$("#rangeExample").rangeSlider({range: {min: 10}});
// Equivalent to
$("#rangeExample").rangeSlider({range: {min: 10, max: false}});

Range deactivation

$("#rangeExample").rangeSlider({range: false});
// Equivalent to
$("#rangeExample").rangeSlider({range: {min: false, max: false}});

// Deactivate minimum range only, and preserve max range
$("#rangeExample").rangeSlider({range: {min: false}});

Ranges in date sliders have to be set using an object, specifying at least one property in the list below.

years
months
weeks
days
hours
minutes
seconds

Scales

The option scales lets you add a ruler with multiple scales to the slider background.

Info: In order to use this option, you have to use a file suffixed by -withRuler-min.js. This option is not supported with standard files.

Basic slider example

$("#rulersExample").rangeSlider({
  scales: [
  // Primary scale
  {
    first: function(val){ return val; },
    next: function(val){ return val + 10; },
    stop: function(val){ return false; },
    label: function(val){ return val; },
    format: function(tickContainer, tickStart, tickEnd){ 
      tickContainer.addClass("myCustomClass");
    }
  },
  // Secondary scale
  {
    first: function(val){ return val; },
    next: function(val){
      if (val % 10 === 9){
        return val + 2;
      }

      return val + 1;
    },
    stop: function(val){ return false; },
    label: function(){ return null; }
  }]
});

Date slider example

var months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sept", "Oct", "Nov", "Dec"];
  $("#dateRulersExample").dateRangeSlider({
    bounds: {min: new Date(2012, 0, 1), max: new Date(2012, 11, 31, 12, 59, 59)},
    defaultValues: {min: new Date(2012, 1, 10), max: new Date(2012, 4, 22)},
    scales: [{
      first: function(value){ return value; },
      end: function(value) {return value; },
      next: function(value){
        var next = new Date(value);

        return new Date(next.setMonth(value.getMonth() + 1));
      },
      label: function(value){
        return months[value.getMonth()];
      },
      format: function(tickContainer, tickStart, tickEnd){
        tickContainer.addClass("myCustomClass");
      }
    }]
  });

The option scales requires an array of objects. Each object represents the configuration of one level.

Scale configuration object can contain 5 functions:

The function first(min, max) [optional]: Must return the ruler first value.; It gives you a way to make the ruler start after the slider minimum. By default, this method returns the slider minimum value.
The function next(value): Must return the next value. This method is required.; Be sure to return a valid date object when using scales with date sliders.
The function label(value, nextValue):string [optional]: Must return the displayed text, for a given interval.; You can return an empty string or null if you don't want labels to be displayed. By default, this method returns value.toString().
The method stop(value):boolean [optional]: Return true to stop the scale generating ticks from a given value.; This method returns false by default.
The function format(tickContainer, tickStartValue, tickEndValue) [optional]: Can be used to customise the tick container DOM element. First argument is passed as a jQuery object.

Step

The option step allows to customize values rounding, and graphically render this rounding. Considering you configured a slider with a step value of 10: it'll only allow your user to choose a value corresponding to minBound + 10n.

Info: This option is deactivated by default

Basic slider (example above)

$("#stepExample").rangeSlider({step: 10});

Edit slider

$("#stepExample").rangeSlider({step: 10});

Date slider

$("#rangeExample").dateRangeSlider({
  step:{
    days: 2
  }});

Step deactivation

$("#rangeExample").rangeSlider({step: false});

Steps in date sliders have to be set using an object, specifying at least one property in this list below.

years
months
weeks
days
hours
minutes
seconds

Type

The option type allows to specify input types in edit slider. Possible values are text (default) and number.

Info: This option is only available on edit sliders

Edit slider (example above)

// Browser needs to support number type
// otherwise you won't see any difference
$("#typeExample").editRangeSlider({type: "number"});

Value labels

The option valueLabels lets you specify a display mode for value labels: hidden, shown, or only shown when moving. Possible values are: show, hide and change.

Info: By default, labels are shown (valueLabels: "show")

Basic slider (example above)

$("#valueLabelsExample").rangeSlider({valueLabels: "change"});

Edit slider

$("#valueLabelsExample").rangeSlider({valueLabels: "change"});

Date slider

$("#valueLabelsExample").dateRangeSlider({valueLabels: "change"});

Wheel mode

The option wheelMode allows to use the mouse wheel to scroll (translate) or zoom (enlarge/shrink) the selected area in jQRangeSlider.

Info: This option is deactivated by default

Warning: This option requires the plugin jquery mousewheel to be loaded.

Basic slider (example above)

$("#wheelModeExample").rangeSlider({wheelMode: "zoom"});

Edit slider

$("#wheelModeExample").rangeSlider({wheelMode: "zoom"});

Date slider

$("#wheelModeExample").dateRangeSlider({wheelMode: "zoom"});

Wheel mode deactivation

$("#wheelModeExample").rangeSlider({wheelMode: null});

Wheel speed

The option wheelSpeed lets you customize the speed of mouse wheel interactions. This parameter requires the wheelMode to be set.

Info: Default value for this option is 4. Increase this value to obtain faster interactions. You can set a negative value if you want to reverse.

Warning: This option requires the plugin jquery mousewheel to be loaded.

Basic slider (example above)

$("#wheelSpeedExample").rangeSlider({wheelMode: "scroll", wheelSpeed: 30});

Edit slider

$("#wheelSpeedExample").rangeSlider({wheelMode: "scroll", wheelSpeed: 30});

Date slider

$("#wheelSpeedExample").dateRangeSlider({wheelMode: "scroll", wheelSpeed: 30});

Binding events

You can attach event handlers to the slider using jQuery functions such as bind() or on().

// For earlier versions if jQuery, but still supported
$("#slider").bind("valuesChanging", function(e, data){
  console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);
});

// Preferred method
$("#slider").on("valuesChanging", function(e, data){
  console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);
});

// Possible use, if sliders are constructed/destroyed many times
$(document).on("valuesChanging", ".ui-rangeSlider", function(e, data){
  console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);
});

Values changing

Use the event valuesChanging if you want to intercept events while the user is moving an element in the slider.

Warning: Use this event wisely, because it is fired very frequently. It can have impact on performance. When possible, prefer the valuesChanged event.

$("#slider").bind("valuesChanging", function(e, data){
  console.log("Something moved. min: " + data.values.min + " max: " + data.values.max);
});

Values changed

Use the event valuesChanged when you want to intercept events once values are chosen. This event is only triggered once after a move.

$("#slider").bind("valuesChanged", function(e, data){
  console.log("Values just changed. min: " + data.values.min + " max: " + data.values.max);
});

User values changed

Like the valuesChanged event, the userValuesChanged is fired after values finished changing. But, unlike the previous one, userValuesChanged is only fired after the user interacted with the slider. Not when you changed values programmatically.

// This event will be fired
$("#slider").bind("valuesChanged", function(e, data){
  console.log("Will be executed");
});

// This event will not ne fired
$("#slider").bind("userValuesChanged", function(e, data){
  console.log("Will NOT be executed");
});

// Changing values programmatically
$("#slider").rangeSlider("values", 10, 20);

Executing methods

Methods on sliders (as all jQuery UI widgets) have to be called in a special way. See examples below.

Basic slider

// Use the slider method to call methods
// First argument: method name
// Next arguments: method arguments
$("#slider").rangeSlider("values", 10, 20);

Edit slider

// Use the slider method to call methods
// First argument: method name
// Next arguments: method arguments
$("#slider").editRangeSlider("values", 10, 20);

Date slider

// Use the slider method to call methods
// First argument: method name
// Next arguments: method arguments
$("#slider").dateRangeSlider("values", new Date(2012, 0, 1), new Date(2012, 0, 31));

Bounds

The method bounds([min, max]) gets or sets the bounds. You can get and change bounds with this method or with the bounds option.

bounds() accepts zero or two arguments. If both arguments are provided, then this method initializes slider's bounds to given values. In both cases, it returns bounds values.

Info: bounds() always returns an object containing the properties min and max.

Get values

// Basic slider
var basicSliderBounds = $("#slider").rangeSlider("bounds");
console.log(basicSliderBounds.min + " " + basicSliderBounds.max);

// Edit slider
var editSliderBounds = $("#editSlider").editRangeSlider("bounds");
console.log(editSliderBounds.min + " " + editSliderBounds.max);

// Date slider
var dateSliderBounds = $("#dateSlider").dateRangeSlider("bounds");
console.log(dateSliderBounds.min.toString() + " " + dateSliderBounds.max.toString());

Set values

// Basic slider
$("#slider").rangeSlider("bounds", 10, 20);

// Edit slider
$("#editSlider").editRangeSlider("bounds", 20, 100);

// Date slider
$("#dateSlider").dateRangeSlider("bounds", new Date(2012, 0, 1), new Date(2012, 0, 31));

Destroy

The method destroy() allows you to remove a slider from your page. It releases memory and removes all DOM elements added by the slider constructor.

Destroy Re-create

Basic slider

$("#slider").rangeSlider("destroy");

Edit slider

$("#slider").editRangeSlider("destroy");

Date slider

$("#slider").dateRangeSlider("destroy");

Min / max

Methods min([value]) and max([value]) can be used to get or set minimum/maximum selected value in the slider.

Both methods accept one optional argument. When used, this value is set as a new minimum/maximum value for the selected range. This methods always return new value for the minimum/maximum value of selected range.

Get values

// Basic slider
var basicSliderMin = $("#slider").rangeSlider("min");
console.log(basicSliderMin);

// Edit slider
var editSliderMin = $("#editSlider").editRangeSlider("min");
console.log(editSliderMin);

// Date slider
var dateSliderMax = $("#dateSlider").dateRangeSlider("max");
console.log(dateSliderMax.toString());

Set values

// Basic slider
$("#slider").rangeSlider("min", 10);

// Edit slider
$("#editSlider").editRangeSlider("min", 20);

// Date slider
$("#dateSlider").dateRangeSlider("max", new Date(2012, 1, 1));

Resize

The method resize() can be used to update slider size after a change in parent's size. This method is automatically called on window resize.

Warning: if you instanciate a slider in an hidden parent, you must call resize() right after displaying the parent. Otherwise, sliders won't work.

Click me to display hidden slider

// Parent is hidden when instanciating this slider
$("#hiddenSlider").rangeSlider();
$("#magicButton").click(function(){
  $('#hiddenParent').show();
  
  // Calling this method forces the slider to update itself
  // and display correctly
  $('#hiddenSlider').rangeSlider('resize');
  
  $(this).detach();
  return false;
});

Scroll left/right

Methods scrollLeft(pixels) and scrollRight(pixels) allow you to simulate click on slider arrows. You can adjust speed by increasing/decreasing the amount.

Scroll left Scroll right

$("#scrolledSlider").rangeSlider();

$("#scrollLeft").click(function(){
  $('#hiddenSlider').rangeSlider('scrollLeft', 10);
  return false;
});

$("#scrollRight").click(function(){
  $('#hiddenSlider').rangeSlider('scrollRight', 10);
  return false;
});

Values

The method values([min, max]) can be used for getting current selected values, and setting new values.

Info: values() returns an object containing properties min and max.

Get values

// Basic slider
var basicValues = $("#slider").rangeSlider("values");
console.log(basicValues.min + " " + basicValues.max);

// Edit slider
var editValues = $("#editSlider").editRangeSlider("values");
console.log(editValues.min + " " + editValues.max);

// Date slider
var dateValues = $("#dateSlider").dateRangeSlider("values");
console.log(dateValues.min.toString() + " " + dateValues.max.toString());

Set values

// Basic slider
$("#slider").rangeSlider("values", 10, 20);

// Edit slider
$("#editSlider").editRangeSlider("values", 20, 100);

// Date slider
$("#dateSlider").dateRangeSlider("values", new Date(2012, 0, 1), new Date(2012, 0, 31));

Zoom in/out

Methods zoomIn(speed) and zoomOut(speed) allow you to enlarge/reduce selected range in the slider.

Zoom in Zoom out

// Basic slider
$("#slider").rangeSlider("zoomIn", 10);

// Edit slider
$("#editSlider").editRangeSlider("zoomIn", 27);

// Date slider
$("#dateSlider").dateRangeSlider("zoomOut", 42);

Quick start

Prerequisites

Basic slider

Edit slider

Date slider

Multiple sliders

Options

Get and set options

Arrows

Bounds

Default values

Delay out

Duration in/out

Formatter

Range

Scales

Step

Type

Value labels

Wheel mode

Wheel speed

Events

Binding events

Values changing

Values changed

User values changed

Methods

Executing methods

Bounds

Destroy

Min / max

Resize

Scroll left/right

Values

Zoom in/out