Getting Started

To use the Slider control, include the following source files in your web page with the script tag:

  <!-- Dependencies --> 
  <script src = "http://yui.yahooapis.com/2.5.1/build/yahoo-dom-event/yahoo-dom-event.js" ></script>
  <script src = "http://yui.yahooapis.com/2.5.1/build/dragdrop/dragdrop-min.js" ></script>
  
  <!-- Slider source file --> 
  <script src = "http://yui.yahooapis.com/2.5.1/build/slider/slider-min.js" ></script>

The Slider component is defined by YAHOO.widget.Slider.

Basic HTML/CSS Setup

To create a slider you will need ID references to two page elements: one for the slider background and one for the thumb. The thumb should be a child of the background element.

<div id="sliderbg">
   <div id="sliderthumb"><img src="sliderthumbimg" /></div>
</div>

The elements can be styled as desired, but both elements should be positioned (eg., either relative or absolute). As the background area is clickable, the size of the elements matters. In typical implementations you will need to make the background width (for horizontal sliders) or height (for vertical sliders) equal the total number of pixels you want the slider to be able to move plus the width or height of the thumb element.

The following graphic illustrates the layout for a horizontal Slider (note: not to scale, and the dimensions are just an example, not a recommendation):

Initializing the Slider

The following example creates a horizontal slider object.

var slider;
function sliderInit() {
   slider = YAHOO.widget.Slider.getHorizSlider("sliderbg", "sliderthumb", 0, 200);
}

The Slider instance in this example is configured so that it can be moved 200 pixels to the right, and 0 pixels to the left. It is also possible to configure the slider thumb to start in the center of the background, which would make sense if your default landing zone or zero value is in the middle of the range.

The getHorizSlider method produces a horizontal slider. The getVertSlider method produces a vertical slider. The full constructor for both looks like this:

YAHOO.widget.Slider.getHorizSlider(string bgid, string thumbid, int leftup, int rightdown, [int tick])

Where:

• bgid is the id of the slider background
• thumbid is the id of the slider thumb
• leftup is the number of pixels the slider can move left or up (depending on orientation)
• rightdown the number of pixels the slider can move right or down (depending on orientation)
• tick is the optional tick interval (see Setting up Tick Marks for more information)

See the additional topics below in Using Slider, below, or on the Examples page for functional examples.

Using Slider

This section describes customizations to the Slider. It contains these sections:

• Setting Up Tick Marks
• Creating Slider Animation
• Handling Slider Events
• The Region Slider
• Dual Thumb Slider

Setting Up Tick Marks

Sometimes you may want your slider to move in fixed pixel increments instead of pixel by pixel. Slider supports this with an optional fifth parameter to the getHorizSlider and getVertSlider methods for the tick interval. The following will produce a vertical slider with tick positions every 20 pixels:

var slider;
   function sliderInit() {
   slider = YAHOO.widget.Slider.getVertSlider("sliderbg", "sliderthumb", 0, 200, 20);
}

When the background is clicked, or the thumb dragged, the slider automatically snaps to the nearest tick position.

Creating Slider Animation

If you include the YUI Animation Utility in your web page, the slider animates when its background is clicked. The animation is a smooth "ease-in" transition unless you define tick marks for the slider. In that case the slider snaps to all tick marks on its way to the final destination.

Animation may not be desirable in some implementations. Some slider animations (for example, those using a CSS background image for the slider thumb) may cause performance issues for some browsers (notably IE). In the case of the thumb performance can be improved by using a slider image (<img src="...">) rather than a CSS background on the slider HTML element.

If you prefer not to use animation, you can disable animation either by omitting the reference to the Animation class or by explicitly turning it off:

var slider;
function sliderInit() {
   slider = YAHOO.widget.Slider.getHorizSlider("sliderbg", "sliderthumb", 100, 100);
   slider.animate = false;
}

Handling Slider Events

The Slider component has a change event that is triggered when the slider thumb is moved. The change event provides (as an argument) the number of pixels the thumb has moved from the position it was in when the component was initialized.

var slider;
function sliderInit() {
   slider = YAHOO.widget.Slider.getHorizSlider("sliderbg", "sliderthumb", 100, 100);
   slider.subscribe("change", displayNewValue);
}

function displayNewValue(offsetFromStart) {
   // determine the actual value from the offset
   var newVal = (offsetFromStart + myStartVal * myScale);
   alert(newVal);

   // If animation is turned on this event fires continuously during the animation.
   // You can evaluate the moveComplete property to determine if the animation
   // is complete.  Alternatively, use the slideEnd event.
   if (this.moveComplete) {
       alert("moveComplete");
   }
}

Sliders also have slideStart and slideEnd events that fire the beginning an end of the slide operation:

var slider;
function sliderInit() {
   slider = YAHOO.widget.Slider.getHorizSlider("sliderbg", "sliderthumb", 100, 100);

   slider.subscribe("slideStart", function() {
        alert("slideStart");
      });

   slider.subscribe("slideEnd", function() {
        alert("slideEnd");
      });
}

The Region Slider

A two-dimensional Slider is referred to as a Region Slider. Region Sliders report two values in the change event (x offset, y offset) and have their own method for setting value in JavaScript: setRegionValue takes x offset and y offset as arguments, followed by the boolean flag for skipping animation. Design considerations regarding range and thumb width apply in both vertical and horizontal dimensions.

The following code sample illustrates the instantiation of a Region Slider whose thumb can move 0 pixels to the left, 300 to the right, 0 up, and 400 down. The second line illustrates setting the thumb position by script to a position of 263 on the x-axis and 314 on the y-axis.

var slider = YAHOO.widget.Slider.getSliderRegion("sliderbg", "sliderthumb", 0, 300, 0, 400);
slider.setRegionValue(263, 314, true);

The Dual Thumb Slider

Another Slider variation is the DualSlider, a horizontal or vertical Slider with two movable thumbs. At its core, the DualSlider is just two Sliders sharing the same background element.

The Slider instances that compose the DualSlider are stored in properties minSlider and maxSlider. If you need to set specific Slider configurations, such as turning off animation, do the following:

var dual_slider = YAHOO.widget.Slider.getHorizDualSlider( "sliderbg","minthumb","maxthumb",200); // Turn off thumb animation for the DualSlider dual_slider.minSlider.animated = false; dual_slider.maxSlider.animated = false;

change event subscribers are passed the DualSlider instance as the first parameter. The minSlider or maxSlider instance is passed as the parameter to slideStart and slideEnd subscribers (depending on which thumb is activated).

DualSliders maintain two read only properties, minVal and maxVal, for the current positions of the two thumbs. To set the values in your code, use methods setMinValue(n), setMaxValue(n), or setValues(n,n).

By default, DualSlider will let the thumbs bump up against one another, but not overlap. Additional space can be maintained between the thumbs using the minRange property.

var dual_slider = YAHOO.widget.Slider.getHorizDualSlider( "sliderbg","minthumb","maxthumb",200); // Maintain a minimum of 10px distance between the inner edges of the thumbs dual_slider.minRange = 10;

Keep in mind that minVal and maxVal are calculated from the center of the thumbs. Unless the minRange is overridden to allow the thumbs to overlap, the minimum value difference will be the sum of the inner portion of the thumbs from their respective mid points.

The min and max thumbs must both be initially position: absolute at the zero point on the background element. DualSlider will place the max thumb at the end of the range during initialization. You may request specific initial values in the sixth argument to the constructor.

<style type="text/css"> #sliderbg { position: relative; height: 20px; width: 220px; background: #fff url(yourbgimage.png) repeat-x 0 0; } #minthumb, #maxthumb { position: absolute; height: 20px; width: 20px; left: 0; /* assumed, but for redundancy */ } </style> <div id="sliderbg"> <div id="minthumb"><img src="yourthumbimage.png" alt="Thumb for min value in range" height="20" width="20"></div> <div id="maxthumb"><img src="yourthumbimage.png" alt="Thumb for max value in range" height="20" width="20"></div> </div> <script type="text/javascript"> (function () { var range = 200; var tickSize = 0; // Values assigned during instantiation var initVals = [ 60, 130 ]; // During instantiation, the min thumb will be moved to offset 60 // and the max thumb to offset 130. var dual_slider = YAHOO.widget.Slider.getHorizDualSlider( "sliderbg","minthumb","maxthumb", range, tickSize, initVals); })(); </script>

YUI on Mobile: Using Slider Control with "A-Grade" Mobile Browsers

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

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 YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.