3476N/A<div id="promo" class="component">
3476N/A The Slider widget is a UI control that enables the user to adjust
3476N/A values in a finite range along a horizontal or vertical axis.
3476N/A Typically, the Slider widget is used in a web application as a visual
3476N/A replacement for an input box that takes a number as input.
3476N/A<h2 id="using">Using Sliders</h2>
3476N/A<h3 id="anatomy">Anatomy of a Slider</h3>
3476N/A A Slider is comprised of a thumb that slides along a rail. In the DOM, the
3476N/A thumb is a child of the rail element. The visualization of the rail is
3476N/A created by applying a CSS background image to the rail element and two
3476N/A child elements used to display the rail's end caps. The thumb contains two
3476N/A <code><img></code> elements, one for the thumb graphic and one for
3476N/A its shadow. Using an <code><img></code> in the DOM rather than a
3476N/A background image for the thumb circumvents a performance issue in older
3476N/A versions of Internet Explorer.
3476N/A The rail element is contained within the standard <code>contentBox</code>
3476N/A and <code>boundingBox</code> common to all YUI 3 Widgets.
3476N/A Like other form controls, Sliders are inline elements.
3476N/A The complete markup of a Slider is as follows:
3476N/A<span class="yui3-widget yui3-sliderbase yui-slider">
3476N/A <span class="yui3-slider-content yui3-slider-x"><!-- or slider-y -->
3761N/A <span class="yui3-slider-rail">
3476N/A <span class="yui3-slider-rail-cap-left"></span><!-- or cap-top -->
3476N/A <span class="yui3-slider-rail-cap-right"></span><!-- or cap-bottom -->
3761N/A <span class="yui3-slider-thumb">
3761N/A <img class="yui3-slider-thumb-shadow">
3761N/A <img class="yui3-slider-thumb-image">
3476N/A<h4 id="appearance">Appearance</h4>
3476N/A This is the appearance of a Slider with default Sam skin applied:
3476N/A See the <a href="#skinning">skinning</a> section below for tips on creating
3476N/A your own skin or using one of the prepackaged skins available for Slider as
3476N/A<h4 id="thumb_placement">Thumb and end cap placement</h4>
3476N/A The Slider thumb is positioned within the dimensional boundaries of the
3476N/A rail element. The skin CSS positions the rail's end caps just outside the
3476N/A rail. The rail element's height or width, for vertical or horizontal
3476N/A Sliders respectively, is configured by the <code>length</code> attribute.
3476N/A The default <code>length</code> is 150px. Due to the end caps, the actual
3476N/A footprint of the Slider is a few pixels longer than the
3476N/A<h3 id="instantiating">Instantiating and configuring a Slider</h3>
3476N/A There is no required configuration to instantiate a Slider. By default,
3476N/A Sliders are horizontal, 150px wide, and report values from 0 to 100. Below
3476N/A are the configuration attributes available for Slider (excluding those
3476N/A <td>Specifies horizontal or vertical Slider ("y" for vertical)</td>
3769N/A <td>Value at the far left or top of the rail</td>
3476N/A <td>Value at the far right or bottom of the rail</td>
3476N/A <td><code>value</code></td>
3476N/A <td>The initial value, which will be translated into initial thumb placement</td>
3476N/A <td><code>length</code></td>
3476N/A <td>Height of vertical Slider rail; width of horizontal Slider rail</td>
3476N/A <td><code>thumbUrl</code></td>
3476N/A <td>The path to an image to use as the <code><img></code> for the thumb</td>
3476N/A <td>Appropriate thumb image for the configured axis in the current skin</td>
3476N/A <td><code>clickableRail</code></td>
3476N/A <td>Clicking on the rail moves the thumb to that point</td>
3476N/A Here are a few ways to instantiate a Slider:
3476N/AYUI({...}).use('slider',function (Y) {
3476N/A // Use a custom thumb and width
3761N/A // Vertical slider with values that increase from bottom to top and
3476N/A // initialize the thumb in the middle.
3761N/A<h3 id="value">Setting and constraining the Slider value</h3>
3761N/A<h4>Setting and getting Slider values</h4>
3476N/A Like any input element, the most important thing about a Slider is its
3476N/A <code>value</code>. Though <code>value</code> is managed as an attribute,
3476N/A Slider provides two convenience methods for accessing it:
3476N/A <li><code>getValue()</code></li>
3476N/A <li><code>setValue(newVal)</code></li>
3476N/A// Specify value at construction
3476N/A// Get and set the value as an attribute
// Use the Slider API convenience methods
<h4 id="min_max">Constraining Slider values</h4>
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
// Create a horizontal Slider 300px wide with values from -100 to 100
By default, <code>min</code> is <code>0</code>, <code>max</code> is
<code>100</code> and <code>value</code> is <code>0</code>.
<h4 id="vert_min_max"><code>min</code> and <code>max</code> for vertical Sliders</h4>
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.
// Create a vertical Slider with value 0 at the bottom, 100 at the top
min : 100, // vertical Sliders have min at the top
value : 33 // initial value
<h4 id="hidden">Sync the UI if the Slider was rendered off the DOM</h4>
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.
// Create a Slider and render it to an element not on the DOM
var slider = new
Y.Slider({ value: 30 });
// 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>
Sliders fire the following events during operation:
<td><code>slideStart</code></td>
<td>Beginning a thumb drag</td>
<td><code>{ ddEvent: (drag:start event) }</code></td>
<td><code>thumbMove</code></td>
<td>The thumb position is being changed</td>
<td><code>{ ddEvent : (drag:drag event) }</code></td>
<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>
<td><code>slideEnd</code></td>
<td>Finishing a thumb drag</td>
<td><code>{ ddEvent: (drag:end event) }</code></td>
<td><code>railMouseDown</code></td>
<td>The rail was clicked</td>
<td><code>{ ev: (DOM mousedown event) }</code></td>
This is not an exhaustive list. See the <a href="{{apiDocs}}/
module_slider.html">API docs</a> for a complete listing.
<h3 id="skinning">Skinning</h3>
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.
<body class="yui3-skin-sam">
<h4 id="skin_thumbUrl">Using custom thumb or rail images</h4>
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.
// The rail and end cap images are shared in a sprite
.yui3-skin-sam .yui3-slider-x .yui3-slider-rail,
.yui3-skin-sam .yui3-slider-x .yui3-slider-rail-cap-left,
.yui3-skin-sam .yui3-slider-x .yui3-slider-rail-cap-right {
YUI().use( "slider", function (Y) {
<h4 id="skins">Available skins</h4>
Slider is provided with several alternate skins that can be applied by
configuring a skin override in your YUI instance configuration.
The available skins are each provided in a light and dark theme. A few
include optional thumbs or rails (for both light and dark).
<td rowspan="2"><code>yui3-skin-sam</code></td>
<td><img src="{{componentAssets}}
/images/sam.png" alt="Slider with Sam skin"></td>
<td><img src="{{componentAssets}}
/images/sam_lines.png" alt="Slider with Sam skin and alternate rail image"></td>
<td><code>yui3-skin-sam-dark</code></td>
<td rowspan="4"><code>yui3-skin-capsule</code></td>
<td><code>yui3-skin-capsule-dark</code></td>
<td rowspan="2"><code>yui3-skin-round</code></td>
<td><img src="{{componentAssets}}
/images/round.png" alt="Slider with Round skin"></td>
<td><img src="{{componentAssets}}
/images/round_thumb.png" alt="Slider with Round skin and alternate thumb image"></td>
<td><code>yui3-skin-audio-light</code></td>
<td><code>yui3-skin-audio</code></td>
<td><img src="{{componentAssets}}
/images/audio.png" alt="Slider with Audio skin"></td>
Here's an example illustrating using the capsule skin with provided
alternate rail and thumb:
// 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 {
YUI({ skin: { overrides: { slider: [ 'capsule' ] } } })
.use( "slider", function (Y) {
<h4 id="skin_sprites">Skin image sprites</h4>
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
border: 1px solid #d9d9d9;
<img src="{{componentAssets}}
/images/thumb.png" alt="Thumb image sprite showing both thumb and shadow" class="sprite-example">
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
<img src="{{componentAssets}}
/images/rail.png" alt="Rail sprite showing the repeatable rail and both end caps" class="sprite-example">
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.
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.
<h3 id="extending">Extending Slider</h3>
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
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
YUI().use( "slider-base", function (Y) {
// Define a new extension class to calculate values differently
function MyValueClass() {
// Add attribute configuration and prototype to decorate the Slider
ATTRS: { /* new configuration attributes */ },
prototype: { /* additional prototype members and methods */ }
// Combine SliderBase with the new extension class any others to
MyValueClass // Use the new value methods and attributes
// Instantiate and use the new Slider class as you would
Y.Slider
