<div class="intro">
<p>
The Slider widget is a UI control that enables the user to adjust
values in a finite range along a horizontal or vertical axis.
Typically, the Slider widget is used in a web application as a visual
replacement for an input box that takes a number as input.
</p>
</div>
{{>getting-started}}
<h2 id="using">Using Sliders</h2>
<h3 id="anatomy">Anatomy of a Slider</h3>
<h4>DOM structure</h4>
<p>
A Slider is comprised of a thumb that slides along a rail. In the DOM, the
thumb is a child of the rail element. The visualization of the rail is
created by applying a CSS background image to the rail element and two
child elements used to display the rail's end caps. The thumb contains two
<code><img></code> elements, one for the thumb graphic and one for
its shadow. Using an <code><img></code> in the DOM rather than a
background image for the thumb circumvents a performance issue in older
versions of Internet Explorer.
</p>
<p>
The rail element is contained within the standard <code>contentBox</code>
and <code>boundingBox</code> common to all YUI 3 Widgets.
</p>
<p>
Like other form controls, Sliders are inline elements.
</p>
<p>
The complete markup of a Slider is as follows:
</p>
```
<!-- boundingBox -->
<span class="yui3-widget yui3-sliderbase yui-slider">
<!-- contentBox -->
<span class="yui3-slider-content yui3-slider-x"><!-- or slider-y -->
<!-- rail -->
<span class="yui3-slider-rail">
<span class="yui3-slider-rail-cap-left"></span><!-- or cap-top -->
<span class="yui3-slider-rail-cap-right"></span><!-- or cap-bottom -->
<!-- thumb -->
<span class="yui3-slider-thumb">
<img class="yui3-slider-thumb-shadow">
<img class="yui3-slider-thumb-image">
</span>
</span>
</span>
</span>
```
<h4 id="appearance">Appearance</h4>
<p>
This is the appearance of a Slider with default Sam skin applied:
</p>
<img src="{{componentAssets}}/images/horiz_slider.png" alt="Horizontal Sliderwith default Sam skin">
<img src="{{componentAssets}}/images/vert_slider.png" alt="Vertical Slider with default Sam skin">
<p>
See the <a href="#skinning">skinning</a> section below for tips on creating
your own skin or using one of the prepackaged skins available for Slider as
of version 3.1.
</p>
<h4 id="thumb_placement">Thumb and end cap placement</h4>
<p>
The Slider thumb is positioned within the dimensional boundaries of the
rail element. The skin CSS positions the rail's end caps just outside the
rail. The rail element's height or width, for vertical or horizontal
Sliders respectively, is configured by the <code>length</code> attribute.
The default <code>length</code> is 150px. Due to the end caps, the actual
footprint of the Slider is a few pixels longer than the
<code>length</code>.
</p>
<img src="{{componentAssets}}/images/anatomy.png" alt="illustration of the parts and config properties of a Slider">
<h3 id="instantiating">Instantiating and configuring a Slider</h3>
<p>
There is no required configuration to instantiate a Slider. By default,
Sliders are horizontal, 150px wide, and report values from 0 to 100. Below
are the configuration attributes available for Slider (excluding those
inherited from Widget):
</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>axis</code></td>
<td>Specifies horizontal or vertical Slider ("y" for vertical)</td>
<td>"x"</td>
</tr>
<tr>
<td><code>min</code></td>
<td>Value at the far left or top of the rail</td>
<td>0</td>
</tr>
<tr>
<td><code>max</code></td>
<td>Value at the far right or bottom of the rail</td>
<td>100</td>
</tr>
<tr>
<td><code>value</code></td>
<td>The initial value, which will be translated into initial thumb placement</td>
<td>0</td>
</tr>
<tr>
<td><code>length</code></td>
<td>Height of vertical Slider rail; width of horizontal Slider rail</td>
<td>150px</td>
</tr>
<tr>
<td><code>thumbUrl</code></td>
<td>The path to an image to use as the <code><img></code> for the thumb</td>
<td>Appropriate thumb image for the configured axis in the current skin</td>
</tr>
<tr>
<td><code>clickableRail</code></td>
<td>Clicking on the rail moves the thumb to that point</td>
<td>true</td>
</tr>
</tbody>
</table>
<p>
Here are a few ways to instantiate a Slider:
</p>
```
YUI({...}).use('slider',function (Y) {
// Default everything
var slider = new Y.Slider();
slider.render("#slider-parent");
// Use a custom thumb and width
var slider = new Y.Slider({
length : '200px',
thumbImage : '/path/to/local/thumb-image.png'
});
slider.render('#slider-parent');
// Vertical slider with values that increase from bottom to top and
// initialize the thumb in the middle.
var slider = new Y.Slider({
axis : 'y',
min : 100,
max : 0,
value : 50
});
slider.render('#slider-parent');
});
```
<h3 id="value">Setting and constraining the Slider value</h3>
<h4>Setting and getting Slider values</h4>
<p>
Like any input element, the most important thing about a Slider is its
<code>value</code>. Though <code>value</code> is managed as an attribute,
Slider provides two convenience methods for accessing it:
</p>
<ul>
<li><code>getValue()</code></li>
<li><code>setValue(newVal)</code></li>
</ul>
```
// Specify value at construction
var slider = new Y.Slider({
value : 50
});
// Get and set the value as an attribute
var val = slider.get('value');
slider.set('value',val + 10);
// Use the Slider API convenience methods
val = slider.getValue();
slider.setValue(val - 20);
```
<h4 id="min_max">Constraining Slider values</h4>
<p>
A Slider's <code>value</code> is constrained between the configured
<code>min</code> and <code>max</code> attribute values. Values outside
this range are treated as the closer of <code>min</code> or
<code>max</code>.
</p>
```
// Create a horizontal Slider 300px wide with values from -100 to 100
var slider = new Y.Slider({
length : 300,
min : -100,
max : 100
});
slider.setValue(-200); // same as setValue(-100)
```
<p>
By default, <code>min</code> is <code>0</code>, <code>max</code> is
<code>100</code> and <code>value</code> is <code>0</code>.
</p>
<h4 id="vert_min_max"><code>min</code> and <code>max</code> for vertical Sliders</h4>
<p>
Vertical Sliders associate the top edge of the rail with the
<code>min</code> value and the bottom edge of the rail with the
<code>max</code>. If you prefer values to increase from bottom to top,
just flip the specified <code>min</code> and <code>max</code> values.
</p>
```
// Create a vertical Slider with value 0 at the bottom, 100 at the top
var v_slider = new Y.Slider({
axis : 'y',
min : 100, // vertical Sliders have min at the top
max : 0,
value : 33 // initial value
});
```
<h4 id="hidden">Sync the UI if the Slider was rendered off the DOM</h4>
<p>
If a Slider is rendered off the DOM, you must call the Slider's
<code>syncUI()</code> method after attaching it to the DOM in order for the
thumb to be placed correctly. When off DOM, the dimensional information
necessary to place the thumb is unavailable.
</p>
```
// Create a Slider and render it to an element not on the DOM
var container = Y.Node.create("<div></div>");
var slider = new Y.Slider({ value: 30 });
slider.render( container );
...
// Insert the Slider's container into the DOM
Y.one( "body" ).insert( container );
// Call syncUI() to sync the thumb to the current value
```
<h3 id="events">Slider events</h3>
<p>
Sliders fire the following events during operation:
</p>
<table>
<thead>
<tr>
<th>Event</th>
<th>When</th>
<th>Payload</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slideStart</code></td>
<td>Beginning a thumb drag</td>
<td><code>{ ddEvent: (drag:start event) }</code></td>
</tr>
<tr>
<td><code>thumbMove</code></td>
<td>The thumb position is being changed</td>
<td><code>{ ddEvent : (drag:drag event) }</code></td>
</tr>
<tr>
<td><code>valueChange</code></td>
<td>The value attribute is changed by any means</td>
<td>Normal change event signature (<code>newVal</code>, <code>prevVal</code>, etc). When dragging, extra event property <code>ddEvent : (drag:drag event)</code> is added</td>
</tr>
<tr>
<td><code>slideEnd</code></td>
<td>Finishing a thumb drag</td>
<td><code>{ ddEvent: (drag:end event) }</code></td>
</tr>
<tr>
<td><code>railMouseDown</code></td>
<td>The rail was clicked</td>
<td><code>{ ev: (DOM mousedown event) }</code></td>
</tr>
</tbody>
</table>
<p>
This is not an exhaustive list. See the <a href="{{apiDocs}}/module_slider.html">API docs</a> for a complete listing.
</p>
<h3 id="skinning">Skinning</h3>
<p>
Like all widgets in YUI, Slider is skinnable and ships by default with the
Sam skin. To apply the skin CSS, assign the skin's class name to a parent
element of the Slider. Typically it's adequate to just add the class to
the <code><body></code> tag.
</p>
```
<body class="yui3-skin-sam">
```
<h4 id="skin_thumbUrl">Using custom thumb or rail images</h4>
<p>
You can use alternate rail images by specifying a new image path in your
CSS, and alternate thumbs can be targeted in the Slider configuration.
</p>
```
<style type="text/css">
/* The rail and end cap images are shared in a sprite.
* Include the id of the slider container to increase css specificity */
.yui3-skin-sam #slider-parent .yui3-slider-x .yui3-slider-rail,
.yui3-skin-sam #slider-parent .yui3-slider-x .yui3-slider-rail-cap-left,
.yui3-skin-sam #slider-parent .yui3-slider-x .yui3-slider-rail-cap-right {
background-image: url(/path/to/new/rail.png);
}
</style>
<script>
YUI().use( "slider", function (Y) {
var slider = new Y.Slider({
thumbUrl: '/path/to/new/thumb.png'
});
slider.render("#slider-parent");
});
</script>
```
<h4 id="skins">Available skins</h4>
<p>
Slider is provided with several alternate skins that can be applied by
configuring a skin override in your YUI instance configuration.
</p>
```
YUI({
skin: {
overrides: {
slider: [ 'round-dark' ]
}
}
}).use( "slider", ... );
```
<p>
The available skins are each provided in a light and dark theme. A few
include optional thumbs or rails (for both light and dark).
</p>
<table>
<thead>
<tr>
<th>Skin class</th>
<th>Visualization</th>
<th>Optional</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="2"><code>yui3-skin-sam</code></td>
<td><img src="{{componentAssets}}/images/sam.png" alt="Slider with Sam skin"></td>
<td></td>
</tr>
<tr>
<td><img src="{{componentAssets}}/images/sam_lines.png" alt="Slider with Sam skin and alternate rail image"></td>
<td>
<code>rail-x-lines.png</code>
</td>
</tr>
<tr>
<td><code>yui3-skin-sam-dark</code></td>
<td><img src="{{componentAssets}}/images/sam_dark.png" alt="Slider with Dark Sam skin"></td>
<td></td>
</tr>
<tr>
<td rowspan="4"><code>yui3-skin-capsule</code></td>
<td><img src="{{componentAssets}}/images/capsule.png" alt="Slider with Capsule skin"></td>
<td></td>
</tr>
<tr>
<td><img src="{{componentAssets}}/images/capsule_thumb.png" alt="Slider with Capsule skin and alternate thumb image"></td>
<td>
<code>thumb-x-line.png</code>
</td>
</tr>
<tr>
<td><img src="{{componentAssets}}/images/capsule_dots.png" alt="Slider with Sam skin and alternate rail image"></td>
<td>
<code>rail-x-dots.png</code>
</td>
</tr>
<tr>
<td><img src="{{componentAssets}}/images/capsule_lines.png" alt="Slider with Sam skin and alternate rail image"></td>
<td>
<code>rail-x-lines.png</code>
</td>
</tr>
<tr>
<td><code>yui3-skin-capsule-dark</code></td>
<td><img src="{{componentAssets}}/images/capsule_dark.png" alt="Slider with Dark Capsule skin"></td>
<td></td>
</tr>
<tr>
<td rowspan="2"><code>yui3-skin-round</code></td>
<td><img src="{{componentAssets}}/images/round.png" alt="Slider with Round skin"></td>
<td></td>
</tr>
<tr>
<td><img src="{{componentAssets}}/images/round_thumb.png" alt="Slider with Round skin and alternate thumb image"></td>
<td>
<code>thumb-x-grip.png</code>
</td>
</tr>
<tr>
<td><code>yui3-skin-audio-light</code></td>
<td><img src="{{componentAssets}}/images/audio_light.png" alt="Slider with Light Audio skin"></td>
<td></td>
</tr>
<tr>
<td><code>yui3-skin-audio</code></td>
<td><img src="{{componentAssets}}/images/audio.png" alt="Slider with Audio skin"></td>
<td></td>
</tr>
</tbody>
</table>
<p>
Here's an example illustrating using the capsule skin with provided
alternate rail and thumb:
</p>
```
<style type="text/css">
// The rail and end cap images are shared in a sprite
.yui3-skin-capsule .yui3-slider-x .yui3-slider-rail,
.yui3-skin-capsule .yui3-slider-x .yui3-slider-rail-cap-left,
.yui3-skin-capsule .yui3-slider-x .yui3-slider-rail-cap-right {
background-image: url(/path/to/build/slider-base/assets/skins/capsule/rail-x-lines.png);
}
</style>
<script>
YUI({ skin: { overrides: { slider: [ 'capsule' ] } } })
.use( "slider", function (Y) {
var slider = new Y.Slider({
axis : 'y',
min : 1,
max : 5,
value : 3,
length : '100px',
});
slider.render("#slider-parent");
});
</script>
```
<h4 id="skin_sprites">Skin image sprites</h4>
<p>
To reduce the number of resource requests for Slider's visual treatment,
the rail and end caps are combined into one image sprite, and thumb and
shadow into another (examples shown below with borders added for
clarity).
</p>
<style type="text/css">
.sprite-example {
border: 1px solid #d9d9d9;
}
</style>
<img src="{{componentAssets}}/images/thumb.png" alt="Thumb image sprite showing both thumb and shadow" class="sprite-example">
<p>
Thumb and shadow sprite. As noted <a href="#anatomy">above</a>, the thumb
and shadow are both represented as <code><img></code>s in the DOM.
This sprite allows both <code><img></code>s to reference the same
<code>src</code> URL, but masked and positioned appropriately by the skin
CSS. Thumb image and shadow for vertical Sliders are set next to each
other horizontally as shown. Horizontal Slider thumb sprites are stacked
vertically.
</p>
<img src="{{componentAssets}}/images/rail.png" alt="Rail sprite showing the repeatable rail and both end caps" class="sprite-example">
<p>
Rail image (repeated across <code>length</code>), top cap, and bottom cap
sprite. This sprite is assigned in the skin CSS as the
<code>background-image</code> for the rail element and the two end caps.
The CSS <code>background</code> for the rail is set to repeat vertically or
horizontally, relative to the Slider <code>axis</code>. The image need be
only as tall (vertical) or wide (horizontal) as the end caps unless the
rail includes a more involved repeating section, such as the audio skin.
End caps should be aligned against the top edge for vertical rails, or the
left edge for horizontal rails.
</p>
<p>
Standard heights and widths are used for the placement of the image bits
within the sprites to allow for minimal differences between the CSS in one
skin versus another. This allows you to start from an existing skin and
change very little of the CSS (potentially only swapping image URLs) to
achieve a new look and feel.
</p>
<h3 id="extending">Extending Slider</h3>
<p>
Slider is built up from a base implementation (<code>Y.SliderBase</code>)
that has no notion of value. It is just a draggable thumb on a rail. The
<code>slider-value-range</code> submodule provides an extension class that
adds the attributes, API, and logic relating the thumb's position to a
<code>value</code> within a <code>min</code>imum and <code>max</code>imum
range. Similarly, the <code>clickableRail</code> implementation is
relegated to an extension class. These classes are combined with
<code>Y.Base.build</code> to generate the <code>Y.Slider</code> class.
</p>
<p>
If you want to use a different value algorithm or decorate the basic Slider
in other ways, you can write an extension class or <code>Y.extend</code> an
existing extension class and create a new Slider implementation with
<code>Y.Base.build</code>.
</p>
```
YUI().use( "slider-base", function (Y) {
// Define a new extension class to calculate values differently
function MyValueClass() {
this._initValueAlgo();
}
// Add attribute configuration and prototype to decorate the Slider
Y.mix( MyValueClass, {
ATTRS: { /* new configuration attributes */ },
prototype: { /* additional prototype members and methods */ }
});
// Combine SliderBase with the new extension class any others to
// create a new Slider
Y.ClickableRail, // Should also support rail clicks
MyValueClass // Use the new value methods and attributes
] );
// Instantiate and use the new Slider class as you would Y.Slider
var slider = new Y.MySlider({ /* config */ });
slider.render( "#slider-parent" );
});
```