Quinn

Are you viewing this README on Github? Head to the Quinn homepage where all of the examples below are fully interactive.

Quinn is a jQuery-based library which creates sliders (aka. ranges, aka. track bars) for HTML applications. The project is hosted on GitHub; you can report bugs and discuss features on the issue tracker, or direct your tweets at @antw.

$('.slider').quinn();

The library requires jQuery and Underscore.js 0.3.1+.

Quinn has been tested and works in the following environments:

There are no plans to support Internet Explorer 6. The unit tests can be run in your browser.

Quinn was developed by ~antw as part of Quintel Intelligence’s Energy Transition Model application. It is released under the New BSD License.

Downloads

Everything (1.1.0)
Tarball containing JS, CSS, and images
Development Version (1.1.0)
37.2kb, JS only, Uncompressed with comments
Production Version (1.1.0)
3.2kb, JS only, Minified and Gzipped

Table of Contents

Options

Minima and Maxima, Initial Values, Steps, Drawing Options, Multiple Values, Effects, Specific Values, Disabling the Slider

Callbacks

setup, begin, drag, change, abort

Progressive Enhancement

Theming

History

Options

In order to customise the appearance and behaviour of the Quinn slider instance, you may pass extra options when initializing:

$(selector).quinn(optionsHash);

Minima and Maxima min: value, max: value

By default, a Quinn slider allows selection of whole numbers between 0 and 100. By supplying min and max options, you can change these values.

/* Our volume knobs go up to eleven. */
$('.slider').quinn({ min: 0, max: 11 });

Negative values are perfectly acceptable, and the “active bar” (the blue background) will always be anchored at zero.

$('.slider').quinn({ min: -100, max: 100 });

Initial Values value: number

When a slider is created without a default value, it will initialize with the slider in the minimum value position. Supplying a value option results in the slider being created with a different starting value.

$('.slider').quinn({ value: 25 });

Steps step: number

The step option restricts the values which may be selected using the slider to numbers which are divisible by the step without a remainder. For example, a step of 10 only 0, 10, 20, 30, …, n, to be chosen.

$('.slider').quinn({ step: 10 });

If you supply an initial value which can’t be used as it doesn’t “fit” with the step, the value will be rounded to the nearest acceptable point on the slider. For example, an step of 10, and an initial value of 17 will result in the slider being initialized with a value of 20 instead. This behaviour can be disabled for the initial value by also supplying strict: false.

Combining the step option with min and max options permits the creation of sliders with arbitrary values:

$('.slider').quinn({ min: 0, max: 1.21, step: 0.01 });

When using step, your provided minimum and maximum values may be altered to ensure that they “fit” the step correctly. Note that in the example below the minimum value 5 is not available since step: 20 is used. The lower value is instead rounded to 20 (not 0 since this is lower than the minimum chosen when creating the slider). Similarly, 95 is rounded down to the nearest inclusive step, 80.

$('.slider').quinn({ min: 5, max: 95, step: 20 });

Drawing Options drawTo: { left: from, right: to }

Sometimes you might want to draw a slider which is wider than the min and max options you gave it. This is achieved by passing a two-element array as drawTo.

The example below draws the slider from a value of 0 up to 100, but only permits selecting a value between 30 and 70.

$('.slider').quinn({
    min: 30, max: 70, drawTo: { left: 0, right: 100 }
});

Multiple Values value: [value1, value2, ..., valueN]

Instead of a Quinn slider having a single value, it may instead be used to represent a range of values, with a lower and upper value. Simply supply an array with two numeric values.

$('.slider').quinn({ value: [25, 75] });

Quinn isn’t limited to two values; add as many as you want, but with the default renderer using more than two values will disable the blue “delta” bar.

$('.slider').quinn({ value: [15, 30, 70, 85] });

Effects effects: bool effectSpeed: number

Some Quinn actions make use of jQuery effects. For example, clicking on the slider bar immediately changes the value and animates movement of the handle to the new position. Animation length may be altered with the effectSpeed option which may be any valid jQuery animation length (fast, slow, or a number), or disabled completely by setting effects: false.

If the Easing library is available, your default animation easing function will be used.

$('.slider').quinn({ effects: false });

Specific Values only: [value, value, ...]

To create a slider where the user may select only from specific values, use the only option with an array of values which may be chosen.

$('.slider').quinn({ only: [10, 15, 50, 80], value: 50 });

Disabling the Slider disable: bool

When you do not wish the user to be able to interact with the slider, pass false with the disable option:

$('.slider').quinn({ value: 50, disable: true });

Callbacks

The behavior of the slider may be further customised through the use of callback functions which are supplied as part of the options object when creating the slider.

When the user alters the slider position, the order of events firing is:

  1. begin: Each time the user starts changing the slider value.
  2. drag: Repeatedly as the user drags the handle to new positions. If the callbacks all return true, and the value was changed, a redraw event is then fired. redraw is considered internal and should be used only if implementing your own renderer.
  3. change: When the user releases the mouse button.
  4. abort: When the user releases the mouse button, and the change callback returns false.

In addition to supplying callbacks when initializing a slider, you may bind further callbacks to the Quinn instance:

var slider = new $.Quinn(element, options);

slider.on('drag', function (value) {
    console.log(value);
});

slider.on('abort', function (value) {
    console.log('Value reset to ' + value);
});

setup setup: function (currentValue, quinn)

setup is run only once, immediately after the Quinn constructor has completed. Two arguments are supplied: the current value of the slider and the Quinn instance. Note that the slider value given during initialization may differ from the one given to the callback since the constructor adjusts the slider value to fit with the min, max, and step options. The value supplied to the callback is correct.

begin begin: function (currentValue, quinn)

begin is fired as the user starts to adjust the slider value. This happens when they click on the slider bar, or on the handle prior to the slider being dragged to a new position.

drag drag: function (newValue, quinn)

The drag callback is run each time the slider value changes. The function is supplied with two arguments: the new slider value, and the Quinn instance.

function changeValueColour (value) {
    var h = (128 - value * 1.28).toFixed(),
        l = (35 + value * 0.1).toFixed();

    $('.value').css('color', 'hsl('+h+', 50%, '+l+'%)');
}

$('.slider').quinn({
    drag: function (newValue, slider) {
        changeValueColour(newValue);
    },

    setup: function (value, slider) {
        /* Set the initial colour. */
        changeValueColour(value);
    }
});

Be aware that the drag callback is run every time the slider value changes, which can be extremely frequent when dragging the slider handle. This is perfect for “hooking” in to the slider to display the value elsewhere in your UI (such as the examples on this page), to update a graph in real-time, etc, but is not suitable for persisting the slider value to a server unless you like flooding your application with tens of HTTP requests per second. Use change which is fired only after the user has finished dragging the handle.

Explicitly returning false in the callback will prevent the change.

$('.slider').quinn({
    drag: function (newValue, slider) {
        /* Prevent selection of 41 to 59. */
        if (newValue > 40 && newValue < 60) {
            return false;
        }
    }
});

change change: function (newValue, quinn)

change is similar to the to the drag event in that it is fired when the slider value is changed by a user. However, unlike drag it is fired only after the user has finished changing the value. This is defined as clicking the slider bar to change the value, or lifting the left mouse button after dragging the slider handle.

$('.slider').quinn({
    value: 25,

    change: function (newValue, slider) {
        /* Disallow selecting a value over 50, but only
           after the user has finished moving the slider. */
        if (newValue > 50) {
            return false;
        }
    }
});

abort abort: function (restoredValue, quinn)

The abort event is fired once the user has finished adjusting the value (like change) but the change failed either because the change callback returned false, or the user set the slider back to the value it was at before they began dragging.

Progressive Enhancement

In addition to using the Quinn directly, enhancing a <div> element, it can be used to progressively enhance an HTML <input>, including HTML5 range elements. In the case of range or number elements, the value, min, max, and step attributes will be read and used when creating your Quinn element.

<input type="range" value="100" min="10" max="300" step="10" />

If you wish to enhance a plain-ol’ <input> element, you can supply these values as data attributes:

<input type="text" value="5" data-min="-10" data-max="50" />

Events will be set up so that changes to the Quinn element are also made to the HTML input, and vice versa.

$("input[type=range]").quinn();

Theming

Altering Quinn’s appearance is relatively simple. The default style uses a single-image sprite. If you don’t need to resize any of the slider elements, replacing this image with an alternative is all it takes. In some cases, you may need to alter the CSS. For example:

.rainbow .bar .left, .rainbow .bar .main, .rainbow .bar .right,
.rainbow .active-bar .left, .rainbow .active-bar .main,
.rainbow .active-bar .right, .rainbow .handle {
  background-image: url(vendor/rainbow.png);
}

.rainbow .bar, .rainbow .bar .left, .rainbow .bar .main,
.rainbow .bar .right, .rainbow .active-bar .left,
.rainbow .active-bar .main, .rainbow .active-bar .right {
  height: 25px;
}

.rainbow .handle {
  height: 24px;
  width: 24px;
}
function changeValueColour (value) {
    var h = (128 - value * 1.28).toFixed(),
        l = (35 + value * 0.1).toFixed();

    $('.value').css('color', 'hsl('+h+', 50%, '+l+'%)');
}

$('.slider').quinn({
    value: 25,

    drag: function (newValue, slider) {
        changeValueColour(newValue);
    },

    setup: function (value, slider) {
        /* Set the initial colour. */
        changeValueColour(value);
    }
});

History

1.1.0 30 October, 2014

1.0.5 August 16th, 2012

1.0.2 July 11th, 2012

1.0.1 May 10th, 2012

1.0.0 April 14th, 2012

0.4.2 February 10th, 2012

Changed the way touch-support was detected to fix clicking on the handle not working correctly in Chrome 17.

0.4.1 January 20th, 2012

Fix for an occasional error when clicking on the bar of sliders when animation is enabled.

0.4.0 December 8th, 2011

Quinn ranges may now also represent a range of values by providing a two-element array as the value option. Note that this will be the last major Quinn release which will use the current “change” and “commit” callback names; 0.5 will change these to “drag” and “change” respectively.

0.3.9 October 4th, 2011

During onChange callbacks, quinn.value will now be the new value of the slider, and not the previous value.

0.3.8 September 29th, 2011

Added width and handleWidth to manually set the width of these elements. Useful when using Quinn on a wrapper element which hasn’t yet been added to the DOM.

0.3.7 August 18th, 2011

Fix a bug with Firefox 6 where elements positioned absolutely with fractional pixel values would not display correctly.

0.3.6 August 15th, 2011

Fix a rendering error introduced in 0.3.4 where the blue active bar was placed in the wrong position when both slider range values were above or below zero.

0.3.5 August 15th, 2011

Some IE 8 fixes.

0.3.4 August 14th, 2011

The blue “active bar” now originates at zero rather than the lowest slider value, allowing sliders with sub-zero values to be better represented than before.

0.3.3 July 28th, 2011

Add a disabledOpacity option for controlling what opacity is used when disabling.

0.3.1 July 21st, 2011

Small stylesheet adjustment to ensure that the slider handle may be moved all the way to the right of the bar.

0.3.0 June 27th, 2011

Events may be bound to the Quinn instance just like DOM events in jQuery using bind. The onComplete callback has been renamed onCommit.

0.2.1 June 14th, 2011

Quinn has now been tested and fixed for IE7, urgh. Opera has been tested and, unsurprisingly, works perfectly.

0.2.0 June 13th, 2011

stepUp and stepDown have been added which are similar to the methods of the same name on HTML 5 range and number inputs. Quinn instances may now be created using new $.Quinn(...) if you need to hang on to the slider instance after creation. Default theme changed to use a modified version of Aristo. Fixed an issue when using selectable with step when the selectable options didn’t fit the step.

0.1.6 June 10th, 2011

The only option has been added which restricts the choosable values to those which are in the only array. Respects the selectable and range settings. Clicking in the space above the visible slider bar now correctly triggers events.

0.1.4 June 9th, 2011

Adds support for touch devices (iOS, Android, etc). Various small fixes to make the library “more jQuery-like”, including the ability to chain other functions off $.fn.quinn(). “Click-dragging” no longer fires two onComplete events; only one when the user releases the mouse button.

0.1.2 June 9th, 2011

When clicking on the slider bar, the mouse button may be held down to refine the value by dragging the handle. The click and drag actions will fire separate onComplete events.

0.1.0 June 8th, 2011

Initial release on GitHub. Supports most planned features, but tests in Opera and Internet Explorer are not yet complete.