YUI 3: Slider [beta]

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 rich, visual replacement for an input box that takes a number as input.

Getting Started

Include Dependencies

The easiest way to include the source files for Slider and its dependencies is to add the YUI seed file to your page, using the following script tag, and allow the YUI instance to download any additional files which may be required:

  1. <script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>
<script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>

The YUI instance will automatically pull down Slider's source files and any missing dependencies when the slider module is used. This helps you avoid having to manually manage the list of files needed on your page to support multiple components while also optimizing your initial page weight by loading files only when they are required.

If you do want to include file dependencies manually on your page, the YUI Dependency Configurator can be used to determine the list of files you need to include in order to use Slider.

The YUI Instance

Once you have the YUI seed file on your page (yui-min.js), you can create a new YUI instance for your application to use and populate it with the modules you need, specified as the first set of arguments to the use method:

  1. // Create new YUI instance, and populate it with the required modules
  2. YUI().use('slider', function(Y) {
  3.  
  4.     // Slider available, and ready for use.
  5.  
  6. });
// Create new YUI instance, and populate it with the required modules
YUI().use('slider', function(Y) {
 
    // Slider available, and ready for use.
 
});

The last argument passed to use is a callback function. The callback function will be invoked as soon as the YUI instance is done downloading any required files missing from your page. Once those files are loaded, your local YUI instance will be supplemented with the classes which make up the slider module and any modules it depends on. A reference to the populated YUI instance (Y) is passed back to your callback function. Within your callback, then, you can start writing your application code based on your own custom instance of YUI.

For more information on creating instances of YUI and the use method, see the YUI Global object documentation.

Using the Slider Widget

This section describes how to use the Slider Widget in further detail. It contains these subsections:

Anatomy of a Slider

DOM structure

Sliders are comprised of a thumb that slides along a rail. In the DOM, the thumb is a child of the rail element. Typically a visualization of the rail is set as a background image of the rail element via CSS. The thumb, however, often contains an <img> element. Using an <img> in the DOM rather than a background image for the thumb circumvents a performance issue in older versions of Internet Explorer.

The rail element is contained within the standard contentBox and boundingBox common to all YUI 3 Widgets. This is the complete markup of a Slider:

  1. <!-- this is the final DOM structure for Sliders -->
  2. <div class="yui-widget yui-slider"><!-- boundingBox -->
  3.     <div class="yui-slider-content"><!-- contentBox -->
  4.         <div class="yui-slider-rail yui-slider-rail-x"><!-- rail -->
  5.             <div class="yui-slider-thumb"><!-- thumb -->
  6.                 <img class="yui-slider-thumb-image"><!-- OPTIONAL thumbImage -->
  7.             </div>
  8.         </div>
  9.     </div>
  10. </div>
  11.  
<!-- this is the final DOM structure for Sliders -->
<div class="yui-widget yui-slider"><!-- boundingBox -->
    <div class="yui-slider-content"><!-- contentBox -->
        <div class="yui-slider-rail yui-slider-rail-x"><!-- rail -->
            <div class="yui-slider-thumb"><!-- thumb -->
                <img class="yui-slider-thumb-image"><!-- OPTIONAL thumbImage -->
            </div>
        </div>
    </div>
</div>
 

Note: If you are creating a vertical Slider from existing markup, be sure to remove all white space between the thumb and image tags, as IE will add a 3px padding that will throw off the value calculation.

Appearance

The appearance of Sliders with default Sam skin applied is (without the drop shadow):

Horizontal Sliderwith default Sam skin Vertical Slider with default Sam skin

The appearance is entirely customizable, as you can see in the Slider from markup example.

Thumb placement

The Slider thumb is positioned within the dimensional boundaries of the rail, adjusted by the pixel offsets specified in the minGutter and maxGutter configuration properties*. The overall rail width for horizontal Sliders or height for vertical Sliders is configurable using the railSize configuration (more on this below). The height of horizontal Sliders and width of vertical Sliders is left to the implementer to define in CSS.

illustration of the parts and config properties of a Slider

* Negative values for minGutter and maxGutter are supported, and allow the thumb to travel beyond the rail edges.

Instantiating and configuring a Slider

Very little is required to instantiate a Slider. Most configuration properties have defaults, and you can choose to include however much of the markup, noted above, in your page that you wish. Additionally, dimensions defined in CSS for rail and thumb will be used if not explicitly configured.

Below are some common configuration properties:

Property Description Default
axis Specifies horizontal or vertical Slider ("y" for vertical) "x"
min Value at the far left or top of the rail 0
max Value at the far right or bottom of the rail 100
value The initial value, which will be translated into initial thumb placement 0
railSize Height of vertical Slider rail; width of horizontal Slider rail Defaults from width or height config depending on axis, or from CSS dimensions of element with class .yui-slider-rail
rail The element (or its selector string) to use as the rail Generates the element if not provided or found
thumb The element (or its selector string) to use as the thumb Generates the element if not provided or found
thumbImage The element (or its selector string) or a path to an image to use as the <img> for the thumb Element with class yui-slider-thumb-image

It is recommended to specify at least the railSize in the configuration. Here are a few ways to instantiate a Slider:

  1. YUI({...}).use('slider',function (Y) {
  2.  
  3.     // Build everything from script, rendered into a target container
  4.     var slider = new Y.Slider({
  5.         railSize : '150px',
  6.         thumbImage : Y.config.base + 'slider/assets/skins/sam/thumb-classic-x.png'
  7.     });
  8.     slider.render('#slider_parent');
  9.  
  10.     // Vertical slider specifying every Node from existing markup.  Make values
  11.     // increase from bottom to top and start the thumb in the middle.
  12.     var slider = new Y.Slider({
  13.         axis        : 'y',
  14.         boundingBox : '#slider',
  15.         contentBox  : '#slider > div',
  16.         rail        : '#slider .rail',
  17.         thumb       : '#slider .thumb',
  18.         thumbImage  : '#slider .thumb > img',
  19.         min         : 100,
  20.         max         : 0,
  21.         value       : 50
  22.     });
  23.     slider.render();
  24.  
  25.     // When existing markup includes Slider's default classes (see above snippet)
  26.     // it will discover the nodes automatically if a boundingBox or contentBox is
  27.     // specified.  This method also assumes the rail element has CSS width defined.
  28.     var slider = new Y.Slider({ boundingBox : '#slider' }).render();
  29.  
  30. });
  31.  
YUI({...}).use('slider',function (Y) {
 
    // Build everything from script, rendered into a target container
    var slider = new Y.Slider({
        railSize : '150px',
        thumbImage : Y.config.base + 'slider/assets/skins/sam/thumb-classic-x.png'
    });
    slider.render('#slider_parent');
 
    // Vertical slider specifying every Node from existing markup.  Make values
    // increase from bottom to top and start the thumb in the middle.
    var slider = new Y.Slider({
        axis        : 'y',
        boundingBox : '#slider',
        contentBox  : '#slider > div',
        rail        : '#slider .rail',
        thumb       : '#slider .thumb',
        thumbImage  : '#slider .thumb > img',
        min         : 100,
        max         : 0,
        value       : 50
    });
    slider.render();
 
    // When existing markup includes Slider's default classes (see above snippet)
    // it will discover the nodes automatically if a boundingBox or contentBox is
    // specified.  This method also assumes the rail element has CSS width defined.
    var slider = new Y.Slider({ boundingBox : '#slider' }).render();
 
});
 
Choose horizontal or vertical Slider with axis

The orientation of a Slider is controlled by the axis configuration. By default, Sliders are horizontal (axis : "x"). For a vertical Slider, set the axis attribute to "y" during construction.

  1. // Horizontal Slider
  2. var h_slider = new Y.Slider({
  3.     railSize   : '200px',
  4.     thumbImage : Y.config.base+'slider/assets/skins/sam/thumb-classic-x.png'
  5. });
  6.  
  7. // Vertical Slider
  8. var v_slider = new Y.Slider({
  9.     axis       : 'y',
  10.     railSize   : '150px',
  11.     thumbImage : Y.config.base+'slider/assets/skins/sam/thumb-classic-y.png'
  12. });
  13.  
// Horizontal Slider
var h_slider = new Y.Slider({
    railSize   : '200px',
    thumbImage : Y.config.base+'slider/assets/skins/sam/thumb-classic-x.png'
});
 
// Vertical Slider
var v_slider = new Y.Slider({
    axis       : 'y',
    railSize   : '150px',
    thumbImage : Y.config.base+'slider/assets/skins/sam/thumb-classic-y.png'
});
 
Configuring the railSize

For both horizontal and vertical Sliders, the railSize attribute will control the length of the rail Node along the configured axis. railSize accepts any CSS size value string.

railSize : '100px' Slider with railSize: '100px'

railSize : '23em'Slider with railSize: '23em'

In the absence of a configured railSize, its value is defaulted from the width or height attribute (whichever is appropriate), then falling back to the current dimensions of the rail Node along the specified axis.

  1. // Recommended
  2. var slider = new Y.Slider({
  3.     railSize   : '100px',
  4.     thumbImage : 'images/thumb.png'
  5. });
  6.  
  7. // Default from height (may conflict with plugins)
  8. var v_slider = new Y.Slider({
  9.     axis       : 'y',
  10.     height     : '90px',
  11.     thumbImage : 'images/thumb.png'
  12. });
  13.  
  14. // Fallback to width specified in CSS for the rail Node
  15. var h_slider : new Y.Slider({
  16.     boundingBox : '#slider',
  17.     rail        : '#rail',
  18.     thumbImage  : '#rail img'
  19. });
  20.  
// Recommended
var slider = new Y.Slider({
    railSize   : '100px',
    thumbImage : 'images/thumb.png'
});
 
// Default from height (may conflict with plugins)
var v_slider = new Y.Slider({
    axis       : 'y',
    height     : '90px',
    thumbImage : 'images/thumb.png'
});
 
// Fallback to width specified in CSS for the rail Node
var h_slider : new Y.Slider({
    boundingBox : '#slider',
    rail        : '#rail',
    thumbImage  : '#rail img'
});
 

It is recommended to always specify railSize.

Using a thumbImage

In addition to accepting a Node reference or selector string, the thumbImage configuration will also accept a url to an image resource.

  1. var slider = new Y.Slider({
  2.     railSize : '100px',
  3.     thumbImage : 'images/blue_thumb.png'
  4. });
  5.  
var slider = new Y.Slider({
    railSize : '100px',
    thumbImage : 'images/blue_thumb.png'
});
 

When a Slider is render()ed, but the configured thumbImage hasn't yet loaded, the completion of the render process is postponed until the image's load or error event fires.

In the intervening time, the Slider value can be modified and the thumb will be placed accordingly when available.

If, however, the url provided as the thumbImage value results in an error (e.g. 404), a default style will be applied so the Slider remains functional, though certainly less attractive.

screen capture showing the fallback display for a failed thumbImage
Adjusting the slide range with minGutter and maxGutter

As illustrated in the Thumb placement section above, the available range of thumb movement within the configured railSize can be reduced or increased by specifying gutters.

minGutter and maxGutter accept numeric values that are treated as pixel distances from the respective edge of the rail element. Positive values decrease the thumb's range; negative values increase it by allowing the thumb to travel outside the rail's dimensional boundaries. By default, both are set to 0.

Using negative gutters may be appropriate if you want the center point of your thumb image to move to the ends of a rail defined by a repeating background image. Conversely, if your rail's background image has end caps, you may want to limit the thumb movement to be within these. The Slider from markup example does the latter.

  1. var timid = new Y.Slider({
  2.     railSize : '200px',
  3.     minGutter: 50, // 200 - 50 = 150px
  4.     maxGutter: 50  // 150 - 50 = 100px thumb range
  5. });
  6.  
  7. var breakOnThru = new Y.Slider({
  8.     railSize : '100px',
  9.     minGutter: -25, // 100 - -25 = 125px
  10.     maxGutter: -50  // 125 - -50 = 175px thumb range
  11. });
  12.  
var timid = new Y.Slider({
    railSize : '200px',
    minGutter: 50, // 200 - 50 = 150px
    maxGutter: 50  // 150 - 50 = 100px thumb range
});
 
var breakOnThru = new Y.Slider({
    railSize : '100px',
    minGutter: -25, // 100 - -25 = 125px
    maxGutter: -50  // 125 - -50 = 175px thumb range
});
 

Setting and constraining the Slider value

Setting and getting Slider values

Like any input element, the most important thing about a Slider is its value. Though value is managed as an attribute, Slider provides two convenience methods for accessing it:

  • getValue()
  • setValue(newVal)
  1. // Specify value at construction
  2. var slider = new Y.Slider({
  3.     railSize : '100px',
  4.     thumbImage : 'images/thumb.png',
  5.     value      : 50
  6. });
  7.  
  8. // Get and set the value as an attribute
  9. var val = slider.get('value');
  10.  
  11. slider.set('value',val + 10);
  12.  
  13. // Use the Slider API getter and setter
  14. val = slider.getValue();
  15.  
  16. slider.setValue(val - 20);
  17.  
// Specify value at construction
var slider = new Y.Slider({
    railSize : '100px',
    thumbImage : 'images/thumb.png',
    value      : 50
});
 
// Get and set the value as an attribute
var val = slider.get('value');
 
slider.set('value',val + 10);
 
// Use the Slider API getter and setter
val = slider.getValue();
 
slider.setValue(val - 20);
 
Constraining Slider values

A Slider's value must be between the configured min and max attribute values.

  1. // Create a horizontal Slider 20ems wide with values from -100 to 100
  2. var slider = new Y.Slider({
  3.     railSize : '20em',
  4.     min      : -100,
  5.     max      : 100
  6. });
  7.  
  8. slider.setValue(-200); // FAIL
  9. slider.setValue(20);   // OK
  10.  
// Create a horizontal Slider 20ems wide with values from -100 to 100
var slider = new Y.Slider({
    railSize : '20em',
    min      : -100,
    max      : 100
});
 
slider.setValue(-200); // FAIL
slider.setValue(20);   // OK
 

By default, min is 0, max is 100 and value is 0.

min and max for vertical Sliders

Vertical Sliders associate the top edge of the rail with the min value and the bottom edge of the rail with the max. If you prefer values to increase from bottom to top, just flip the specified min and max values.

  1. // Create a vertical Slider 90px tall with value 0 at the bottom, 100 at the top
  2. var v_slider = new Y.Slider({
  3.     axis     : 'y',
  4.     railSize : '90px',
  5.     min      : 100, // vertical Sliders have min at the top
  6.     max      : 0,
  7.     value    : 33   // initial value
  8. });
  9.  
// Create a vertical Slider 90px tall with value 0 at the bottom, 100 at the top
var v_slider = new Y.Slider({
    axis     : 'y',
    railSize : '90px',
    min      : 100, // vertical Sliders have min at the top
    max      : 0,
    value    : 33   // initial value
});
 

Slider events

Sliders fire the following events during operation:

Event When Payload
slideStart Beginning a thumb drag { ddEvent: (drag:start event) }
thumbDrag The thumb is being dragged { ddEvent : (drag:drag event) }
valueChange The value attribute is changed by any means Normal change event signature (newVal, prevVal, etc). When dragging, extra event property ddEvent : (drag:drag event) is added
positionThumb After the value is changed via set("value", n) or setValue(n) { value : (new value), offset : (calculated pixel offset for thumb) }
slideEnd Finishing a thumb drag { ddEvent: (drag:end event) }
sync Synchronizing the UI with the Slider state (no special payload)

This is not an exhaustive list. See the API docs for a complete listing.

Skinning

Trigger the appropriate skin for your Slider by assigning a skin class to an element that is a parent element to the Slider. It's usually sufficient to just assign the skin class to the <body>.

  1. <body class="yui-skin-sam">
  2.  
<body class="yui-skin-sam">
 

The Sam skin is the default skin that is provided with YUI and provides a minimal visualization in the form of one rail and thumb image for each vertical and horizontal Sliders. The skin includes the following simple CSS to apply the appropriate background image to the rail element:

  1. .yui-skin-sam .yui-slider-rail-x {
  2.     background: url("rail-classic-x.png") repeat-x 0 7px;
  3.     min-height: 19px;
  4.     *height: 19px;
  5. }
  6.  
  7. .yui-skin-sam .yui-slider-rail-y {
  8.     background: url("rail-classic-y.png") repeat-y 7px 0;
  9.     min-width: 19px;
  10.     *width: 19px;
  11. }
  12.  
.yui-skin-sam .yui-slider-rail-x {
    background: url("rail-classic-x.png") repeat-x 0 7px;
    min-height: 19px;
    *height: 19px;
}
 
.yui-skin-sam .yui-slider-rail-y {
    background: url("rail-classic-y.png") repeat-y 7px 0;
    min-width: 19px;
    *width: 19px;
}
 

The following images are also provided with the Sam skin:

Image resources
image file width height
thumb-classic-x.png 15 19
thumb-classic-y.png 18 13
 
 rail-classic-x.png 1 * 4
 
 rail-classic-y.png 3 1 *

* rail images repeated for clarity.

Support & Community

Forums & Blog

YUI 3 discussion forums are hosted on YUILibrary.com.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Examples That Make Use of Slider

YUI's Slider Widget on Delicious

Copyright © 2010 Yahoo! Inc. All rights reserved. Copyright | Privacy Policy | Terms of Use | Job Openings