jQRangeSlider - Documentation

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)  
});

// Set multiple options at once
$("#dateSlider").dateRangeSlider(
  "option",
  { 
    bounds: {
      min: new Date(2012, 0, 1),
      max: new Date(2012, 11, 31)  
    },
    enabled: false
  }
);

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

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

Date slider

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

Enabled

The option enabled allows you to configure a read-only slider.

Warning: This option block all user input, but do not block modifications in javascript. Please make sure your code is correctly reacting to the disabled state..

Basic slider (example above)

$("#disabledExample").rangeSlider({
  enabled: false
});

Edit slider

$("#disabledExample").editRangeSlider({
  enabled: false
});

Date slider

$("#disabledExample").dateRangeSlider({
  enabled: false
});

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

Symmetric positionning

The option symmetricPositionning changes the way handles are positionned on the slider. This option is usefull when customizing how the slider is displayed.

Use this option when you want to show handles and make them clearly select the range.

Warning: This option must be used with a minimum (possibly equal to 0) range value.

Warning: This option must not be used with a scale. Positionning in this case does not corresponds to a possible scale.

Basic slider (example above)

$("#symmetricExample").rangeSlider({
  symmetricPositionning: true,
  range: {min: 0}  
});

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});