Sliders

As the files names suggests, this feature shares common styles and methods with the progress feature, you will find many similar elements between both.

The template provides a complete set of styles to build sliders, either available as raw code and through a powerful API:

Markup

If you want to use the slider style without using the API, here is an example of complete slider markup:

0% 20% 40% 60% 80% 100% Doh! Good Yeah!

For RTL version, use right position instead of left.

<span class="slider" style="width: 250px">

	<!-- Progress bar -->
	<span class="slider-bar" style="width: 31%"></span>

	<!-- Inner marks -->
	<span class="inner-mark" style="left: 51px"></span>
	<span class="inner-mark" style="left: 101px"></span>
	<span class="inner-mark" style="left: 150px"></span>
	<span class="inner-mark" style="left: 200px"></span>

	<!-- Top marks -->
	<span class="top-mark" style="left: 1px"><span class="mark-label align-right">0%</span></span>
	<span class="top-mark" style="left: 51px"><span class="mark-label">20%</span></span>
	<span class="top-mark" style="left: 101px"><span class="mark-label">40%</span></span>
	<span class="top-mark" style="left: 150px"><span class="mark-label">60%</span></span>
	<span class="top-mark" style="left: 200px"><span class="mark-label">80%</span></span>
	<span class="top-mark" style="left: 250px"><span class="mark-label align-left">100%</span></span>

	<!-- Bottom marks -->
	<span class="bottom-mark" style="left: 1px"><span class="mark-label align-right">Doh!</span></span>
	<span class="bottom-mark" style="left: 125px"><span class="mark-label">Good</span></span>
	<span class="bottom-mark" style="left: 250px"><span class="mark-label align-left">Yeah!</span></span>

	<!-- Cursor -->
	<span class="slider-cursor" style="left: 31%"></span>

</span>

For a vertical slider, add the class vertical to the main element and use left-mark and right-mark instead of top-mark and bottom-mark (with align-top and align-bottom for extremes).

Of course, all marks are optional an can be removed at will:

There is an alternate style for the cursor, and the bar can use any color:

<span class="slider" style="width: 250px">

	<!-- Progress bar -->
	<span class="slider-bar red-gradient" style="width: 31%"></span>

	<!-- Cursor -->
	<span class="slider-cursor knob" style="left: 31%"></span>

</span>

API

To create a slider using the API, you may either using one or two existing inputs, or create a stand-alone slider:

Using one input

Just apply the slider() method to any input (text or hidden) to convert it to a slider. The slider will be created next to the input, and both will then be bound - changes will be applyed to both:

$(selector).slider();

Note that, by default, the input is hidden when the slider is created. If you want to show it, you can use one of the options detailled below:

$(selector).slider({
	hideInput: false
});

Or use inline options (as for the example above):

<input type="text" value="15" class="input mid-margin-right" size="2" data-slider-options='{"hideInput":false}'>

The target input will then have keyboard shortcuts enabled when focused: up and down arrows to change value, shift+arrow for bigger increments.

There is an alternate method: target the element in which the slider must be created, and provide the input in the options. This is usefull for instance if you plan to use a hidden input located on top or at bottom of the page:

$(selector).slider({
	input: '#input'
});

You may pass either a CSS selector string or a jQuery object.

Using two inputs

The syntax is the same for ranges, but use the inputs option (note the final s):

$(selector).slider({
	inputs: ['#input1', '#input2']
});

Using no input

The slider APi can run stand-alone, without any input:

$(selector).slider();

Use the onChange callback option to listen for changes.

Methods

$(selector).slider(options)

Create a slider in the target element, or next to the target element if it is an input
Options may be set using the inline html5 data-slider-options attribute: <div data-slider-options="{'max':200}"></div>

Parameters

@param object options

$(selector).setSliderValue(val1, val2)

Set slider current value(s)

Parameters

@param number val1 the value for single value sliders, or the first handle value for ranges
@param number val2 the value for the second handle (only for ranges)

Options reference

The defaults may be modified at runtime in $.fn.slider.defaults, and options may be passed inline using the data-slider-options attribute

min

Minimum value
Type: number
Default: 0

max

Maximum value
Type: number
Default: 100

round

True to round value, a number to set the float length, or false to not round at all
Type: boolean|int
Default: true

stickToRound

Will stick cursor to the closest rounded value when dragging
Type: boolean
Default: false

step

Size of each interval between min and max, or a list of points to snap the cursor to
Type: number|array
Default: null

stickToStep

Will stick cursor to the closest step value when dragging
Type: boolean
Default: true

value

Start value (ignored in range mode)
Type: number
Default: 50

values

Start values (if set and has 2 elements, enable range)
Type: array(number,
Default: null

input

Input or jQuery selector for input in which to retrieve/save the slider value (ignored in range mode)
Type: jQuery|string
Default: null

inputs

Inputs or jQuery selector for inputs in which to retrieve/save the slider values (if set and has 2 elements, enable range)
Type: array(jQuery|string,
Default: null

hideInput

Use true to hide related input(s)
Type: boolean
Default: true

orientation

Orientation of the slider ('horizontal' or 'vertical')
Type: string
Default: 'horizontal'

barClasses

Class or list of class for the bar
Type: string|array
Default: null

barMode

Mode of progress bar (only for single value): 'min' to range from left to value, 'max' to range from right to value (reverted in RTL)
Type: string
Default: 'min'

innerMarksOverBar

Set to true to show inner marks over the bar
Type: boolean
Default: false

stripes

Enable animated stripes
Type: boolean
Default: false

animatedStripes

True for animated stripes (only on compatible browsers)
Type: boolean
Default: true

darkStripes

True for dark stripes, false for white stripes
Type: boolean
Default: true

stripesSize

Stripes size: 'big', 'normal' or 'thin'
Type: string
Default: 'normal'

knob

Set to true to use knobs as handles
Type: boolean
Default: false

animate

Animate cursors moves
Type: boolean
Default: true

animateSpeed

Speed for animations (any jquery valid value)
Type: string|int
Default: 'fast'

tooltip

Position to show the tooltip with current value, 'auto' for 'top' if the lider is horizontal and 'right' if vertical, or false to disable. For range sliders, use an array of two values - one for each cursor
Type: string|array|boolean
Default: 'auto'

tooltipFormat

Format of tooltip text: null for bare value, pattern string (with [value] as a placeholder) or a function(value)
Type: string|function
Default: null

tooltipOnHover

Always show tooltip or show only on hover
Type: boolean
Default: true

tooltipBiggerOnDrag

Make tooltip bigger on drag (only if it has class 'compact')
Type: boolean
Default: true

tooltipClass

Class or list of class for the tooltip
Type: string|array
Default: ['compact', 'black-gradient', 'glossy']

clickableTrack

Enable quick value selection by clicking on the background
Type: boolean
Default: true

decimalPoint

Character used for decimal point
Type: string
Default: '.'

thousandsSep

Character used for thousands separator
Type: string
Default: ''

zerofill

Fill decimal part with zeros to match desired precision
Type: boolean
Default: true

onStartDrag

Callback when the user starts dragging the cursor, takes one param for value, two for ranges
Type: function
Default: null

onChange

Callback when the slider value is changed, takes one param for value, two for ranges
Type: function
Default: null

onEndDrag

Callback when the user stops dragging the cursor, takes one param for value, two for ranges
Type: function
Default: null

Track options reference

These options are shared with the progress feature:

The defaults may be modified at runtime in $.fn.buildTrack.defaults

size

Width/height of the track (any css value, int will be used as pixels), or false for fluid size
Type: int|string|boolean
Default: 250

classes

Class or list of class for the bar
Type: string|array
Default: null

css

Any extra css styles, in a key/value map
Type: object
Default: {}

orientation

Orientation of the track ('horizontal' or 'vertical')
Type: string
Default: 'horizontal'

innerMarks

Inner marks, may be:

a number

marks will be created each multiple of this number, starting from 'min'

an array

a list of points where marks should be created.

Type: string|array
Default: null

topMarks

Top marks, may be:

a number

marks will be created each multiple of this number, starting from 'min'

an array

a list of points where marks should be created. Each point can be either a number or an object with a value and two optional properties, 'label' and 'align': { value: x, label: 'label', align: 'center' }.
If the point is a number or if 'label' is not set, an automatic label will be created if topLabel is set.
If the point is a number or if 'align' is not set, the value of topLabelAlign will be used.

Type: string|array
Default: null

topLabel

Automatic label for top marks. Use true to display mark value, or a string with [value] as a placeholder for each mark value, for instance: '[value]%'
Type: boolean|string
Default: null

topLabelAlign

Alignement for top marks labels: 'left', 'center' or 'right'
Type: string
Default: 'center'

rightMarks

Right marks, may be:

a number

marks will be created each multiple of this number, starting from 'min'

an array

a list of points where marks should be created. Each point can be either a number or an object with a value and an optional properties, 'label': { value: x, label: 'label' }.
If the point is a number or if 'label' is not set, an automatic label will be created if rightLabel is set.

Type: string|array
Default: null

rightLabel

Automatic label for right marks. Use true to display mark value, or a string with [value] as a placeholder for each mark value, for instance: '[value]%'
Type: boolean|string
Default: null

rightLabelAlign

Alignement for right marks labels: 'top', 'center' or 'bottom'
Type: string
Default: 'center'

bottomMarks

Bottom marks, may be:

a number

marks will be created each multiple of this number, starting from 'min'

an array

a list of points where marks should be created. Each point can be either a number or an object with a value and two optional properties, 'label' and 'align': { value: x, label: 'label', align: 'center' }.
If the point is a number or if 'label' is not set, an automatic label will be created if bottomLabel is set.
If the point is a number or if 'align' is not set, the value of bottomLabelAlign will be used.

Type: string|array
Default: null

bottomLabel

Automatic label for top marks. Use true to display mark value, or a string with [value] as a placeholder for each mark value, for instance: '[value]%'
Type: boolean|string
Default: null

bottomLabelAlign

Alignement for bottom marks labels: 'left', 'center' or 'right'
Type: string
Default: 'center'

leftMarks

Left marks, may be:

a number

marks will be created each multiple of this number, starting from 'min'

an array

a list of points where marks should be created. Each point can be either a number or an object with a value and an optional properties, 'label': { value: x, label: 'label' }.
If the point is a number or if 'label' is not set, an automatic label will be created if leftLabel is set.

Type: string|array
Default: null

leftLabel

Automatic label for left marks. Use true to display mark value, or a string with [value] as a placeholder for each mark value, for instance: '[value]%'
Type: boolean|string
Default: null

leftLabelAlign

Alignement for left marks labels: 'top', 'center' or 'bottom'
Type: string
Default: 'center'

insetExtremes

Automaticaly set alignement (if not set) to inset the labels of marks matching min and max
Type: boolean
Default: false

autoSpacing

Will add spacing margins to the track, matching space required by marks and labels - true to enable, false to disable.
Setting a numeric value will enabled auto-spacing and add this as an extra margin on top of calculated one.
Type: boolean
Default: false

autoSpacingTop

Auto top spacing: true to enable, false to disable, null to inherit from autoSpacing.
Setting a numeric value will enable auto-spacing and add this as an extra margin on top of calculated one.
Type: boolean|int
Default: null

autoSpacingRight

Auto right spacing: true to enable, false to disable, null to inherit from autoSpacing.
Setting a numeric value will enable auto-spacing and add this as an extra margin on top of calculated one.
Type: boolean|int
Default: null

autoSpacingBottom

Auto bottom spacing: true to enable, false to disable, null to inherit from autoSpacing.
Setting a numeric value will enable auto-spacing and add this as an extra margin on top of calculated one.
Type: boolean|int
Default: null

autoSpacingLeft

Auto left spacing: true to enable, false to disable, null to inherit from autoSpacing.
Setting a numeric value will enable auto-spacing and add this as an extra margin on top of calculated one.
Type: boolean|int
Default: null

autoSpacingCenterVertical

When auto-spacing, equalize top and bottom margins to the highest - for instance to keep alignement on baseline
Type: boolean
Default: false

autoSpacingCenterHorizontal

When auto-spacing, equalize left and right margins to the highest - for instance to center in a block
Type: boolean
Default: false