Getting Started

To use the Carousel Control, include the following source files in your web page:

<!-- Core + Skin CSS --> 
<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/carousel/assets/skins/sam/carousel.css">
 
<!-- Dependencies --> 
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script>
 
<!-- Optional: Animation library for animating the scrolling of items --> 
<script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
<!-- Optional: Connection library for dynamically loading items --> 
<script src="http://yui.yahooapis.com/2.9.0/build/connection/connection-min.js"></script>
 
<!-- Source file --> 
<script src="http://yui.yahooapis.com/2.9.0/build/carousel/carousel-min.js"></script>
 

<!-- Core + Skin CSS -->
<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/carousel/assets/skins/sam/carousel.css">
 
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script>
 
<!-- Optional: Animation library for animating the scrolling of items -->
<script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
<!-- Optional: Connection library for dynamically loading items -->
<script src="http://yui.yahooapis.com/2.9.0/build/connection/connection-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/carousel/carousel-min.js"></script>
 

Basic Setup

The Carousel Control can be created with or without existing HTML. In either case, the Carousel's HTML is composed of a container <div> and a list of items within the container <ol> or <ul>. The Carousel Control can construct the navigation elements also, if these are not already provided by the markup.

The Carousel Control is defined by YAHOO.widget.Carousel and can be instantiated two ways:

• Using an existing list <ol> or <ul> element
• Using no existing HTML

Using an existing list <ol> or <ul> element

A Carousel Control can be created from an existing list of items (<li>) within an <ol> element. The component also can be configured to look for <ul> instead of the default <ol> by setting the carouselEl configuration attribute.

<div id="container">
    <ol>
        <li><img alt="" src="..."></li>
        ...
    </ol>
</div>
 

<div id="container">
    <ol>
        <li><img alt="" src="..."></li>
        ...
    </ol>
</div>
 

Pass the id of the Carousel's container element as the first argument to the Carousel's constructor. If any additional configuration is needed, it can be set during the instantiation by specifying them in the object literal that is passed as the second argument to the Carousel's constructor. Finally, call the render method of the Carousel to display the widget.

var carousel = new YAHOO.widget.Carousel("container", {
    isCircular: true // for a circular Carousel
});
carousel.render();
carousel.show(); // display the widget (redundant from 2.8.0), but use if carousel.hide() has been run previously.
 

var carousel = new YAHOO.widget.Carousel("container", {
    isCircular: true // for a circular Carousel
});
carousel.render();
carousel.show(); // display the widget (redundant from 2.8.0), but use if carousel.hide() has been run previously.
 

Beginning with Carousel version 2.8.0, the show method need not be invoked for the initial rendering, just the render method is suffice. However, to display a Carousel again, you still need to invoke show after running hide.

Similarly, to use the <ul> element, the CarouselEl configuration attribute should be set to "UL".

<div id="container">
    <ul>
        <li><img alt="" src="..."></li>
        ...
    </ul>
</div>
 

<div id="container">
    <ul>
        <li><img alt="" src="..."></li>
        ...
    </ul>
</div>
 

var carousel = new YAHOO.widget.Carousel("container", {
    carouselEl: "UL"
});
 

var carousel = new YAHOO.widget.Carousel("container", {
    carouselEl: "UL"
});
 

Using no existing HTML

A Carousel Control can be created purely from JavaScript, without any existing HTML for the Carousel items.

<div id="parentContainerId"></div>
 

<div id="parentContainerId"></div>
 

var carousel = new YAHOO.widget.Carousel("parentContainerId");
carousel.addItem(...); // add an item to the Carousel
carousel.addItems(...); // add multiple items at one go
carousel.render(); // render the widget inside the
                   // parentContainerId container 
 

var carousel = new YAHOO.widget.Carousel("parentContainerId");
carousel.addItem(...); // add an item to the Carousel
carousel.addItems(...); // add multiple items at one go
carousel.render(); // render the widget inside the
                   // parentContainerId container 
 

The constructor is passed with the parent container id within which the Carousel will be created.

Using Carousel

This section describes several common uses and customizations of the Carousel Control:

• Using Carousel with YAHOO.util.Event.onContentReady
• Having the Carousel animate when items are scrolled through
• Setting up auto-play in Carousel
• Revealing a sneak view of the previous and next items in a Carousel
• A vertical Carousel
• Handling Events
• Configuration Attributes

Using the Carousel with YAHOO.util.Event.onContentReady

As the Carousel Control can be used to progressively enhance a list of items, it is recommended that the Carousel Control be instantiated as soon as the contents of the Carousel Widget's container are ready. This helps minimize any flicker or redraw that might occur when the DOM structure is modified during widget instantiation.

To instantiate a Carousel instance as soon as the content for the Carousel's container element is available, use the onContentReady method of the YUI Event Utility. The example below illustrates how to do this. Consider the following markup in your page:

<div id="container">
    <ul>
        <li><img alt="" src="..."></li>
        ...
    </ul>
</div>
 

<div id="container">
    <ul>
        <li><img alt="" src="..."></li>
        ...
    </ul>
</div>
 

To instantiate the Carousel Control as soon as the content is available, pass the id of the container as the first argument to YAHOO.util.Event.onContentReady method. The second parameter to the method is the function in which you instantiate the widget.

YAHOO.util.Event.onContentReady("container", function (ev) {
    var carousel = new YAHOO.widget.Carousel("container");
    carousel.render();
});
 

YAHOO.util.Event.onContentReady("container", function (ev) {
    var carousel = new YAHOO.widget.Carousel("container");
    carousel.render();
});
 

Usage of the onContentReady method is demonstrated in many of the Carousel Widget examples. For more information, read the section titled Using the onAvailable and onContentReady Methods section of the Event utility's landing page.

Specifying how many items to display per page

By default, the Carousel displays three items per page. To override the default, simply set a Carousel's numVisible property to another Number.

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("numVisible", 4);
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("numVisible", 4);
carousel.render();
 

Animated scrolling of the Carousel contents

If you include the YUI Animation Utility in your web page, you can enable animation on item scroll in a Carousel using the following syntax:

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("animation", { speed: 0.5 });
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("animation", { speed: 0.5 });
carousel.render();
 

Alternatively, you can set this property during the instantiation of Carousel itself.

var carousel = new YAHOO.widget.Carousel("container", {
    animation: { speed: 0.5 }
});
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container", {
    animation: { speed: 0.5 }
});
carousel.render();
 

Setting up auto-play in Carousel

By default, the Carousel scrolls its contents only when the previous or next arrows are clicked, or when the pagination control is clicked. You can make the Carousel automatically scroll after a certain delay by setting its autoPlayInterval configuration setting and invoking the startAutoPlay method. The following example illustrates setting this property and also making the Carousel circular.

var carousel = new YAHOO.widget.Carousel("container");
// Set the delay (in milliseconds) to automatically scroll
// the Carousel.
carousel.set("autoPlayInterval", 2000);
carousel.set("isCircular", true); // make the widget circular
carousel.render();
 
// Automatically scroll the Carousel after every
// autoPlayInterval millisecond.
carousel.startAutoPlay();
 

var carousel = new YAHOO.widget.Carousel("container");
// Set the delay (in milliseconds) to automatically scroll
// the Carousel.
carousel.set("autoPlayInterval", 2000);
carousel.set("isCircular", true); // make the widget circular
carousel.render();
 
// Automatically scroll the Carousel after every
// autoPlayInterval millisecond.
carousel.startAutoPlay();
 

Alternatively, you can set this property during the instantiation of Carousel itself.

var carousel = new YAHOO.widget.Carousel("container", {
    autoPlayInterval: 2000,
    isCircular: true
});
carousel.render();
// Automatically scroll the Carousel after every
// autoPlayInterval millisecond.
carousel.startAutoPlay();
 

var carousel = new YAHOO.widget.Carousel("container", {
    autoPlayInterval: 2000,
    isCircular: true
});
carousel.render();
// Automatically scroll the Carousel after every
// autoPlayInterval millisecond.
carousel.startAutoPlay();
 

Revealing a "sneak preview" of the previous and next items in a Carousel

There are times when you want to provide a slight reveal for the items before and after the clipping region in the Carousel Control. This gives the user a sneak preview of the forthcoming items and invites the user to explore the content.

You can set the revealAmount to the percentage of the size of an item to be revealed. The following example illustrates setting the property.

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("revealAmount", 20);
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("revealAmount", 20);
carousel.render();
 

Alternatively, you can set this property during the instantiation of Carousel itself.

var carousel = new YAHOO.widget.Carousel("container", {
    revealAmount: 20
});
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container", {
    revealAmount: 20
});
carousel.render();
 

A vertical Carousel

If you want to display a vertical Carousel Control, you can set the isVertical property to true. The following example illustrates creating a vertical Carousel Widget.

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("isVertical", true);
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("isVertical", true);
carousel.render();
 

Alternatively, you can set this property during the instantiation of Carousel itself.

var carousel = new YAHOO.widget.Carousel("container", {
    isVertical: true
});
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container", {
    isVertical: true
});
carousel.render();
 

A multi-row Carousel

If you want to display a multi-row Carousel Control, you can pass the numVisible property an Array specifying rows and columns (both Numbers). The following example illustrates creating a multi-row Carousel Widget.

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("numVisible", [3, 2]);
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.set("numVisible", [3, 2]);
carousel.render();
 

Handling Events

All events expressed as part of the to subscribe to all of the Carousel Control's API can be subscribed using the on (or addListener) method (as is true of all YUI controls based on the Element Utility). This includes even the DOM-based events like click.

For custom events specific to this component, a data object is passed to the handler function as the first argument. For DOM events, this is the actual event object.

var carousel = new YAHOO.widget.Carousel("container");
carousel.on("click", function (ev) {
    // ev is the standard YUI Event object
});
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.on("click", function (ev) {
    // ev is the standard YUI Event object
});
carousel.render();
 

For the Carousel Control-specific events, the first argument passed to the event listener is the information about the event. This varies based on the event that is triggered. For example, for the scroll events the data object tells you about the first and last visible items in the Carousel and the direction of scroll.

var carousel = new YAHOO.widget.Carousel("container");
carousel.on("beforeScroll", function (obj) {
    // obj contains the following information:
    // {
    //    first: firstVisibleIndex,
    //    last: lastVisibleIndex,
    //    dir: direction of scroll
    // }
});
carousel.render();
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.on("beforeScroll", function (obj) {
    // obj contains the following information:
    // {
    //    first: firstVisibleIndex,
    //    last: lastVisibleIndex,
    //    dir: direction of scroll
    // }
});
carousel.render();
 

Note: If you want to abort the scrolling of the Carousel, you can subscribe to the beforeScroll event and then return the value false to abort scrolling.

The event listeners can be removed via the removeListener method of the Carousel Control.

var carousel = new YAHOO.widget.Carousel("container");
carousel.render();
 
function scrollEvtHandler(obj) {
    // ...
}
 
carousel.addListener("beforeScroll", scrollEvtHandler);
// ...
carousel.removeListener("beforeScroll", scrollEvtHandler);
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.render();
 
function scrollEvtHandler(obj) {
    // ...
}
 
carousel.addListener("beforeScroll", scrollEvtHandler);
// ...
carousel.removeListener("beforeScroll", scrollEvtHandler);
 

Configuration Attributes

The Carousel Control's configuration can be obtained or set at runtime using its get and set methods. For example:

var carousel = new YAHOO.widget.Carousel("container");
carousel.render();
alert(carousel.get("numVisible")); // alerts 3 (default)
carousel.set("numVisible", 1);     // override the default
alert(carousel.get("numVisible")); // alerts 1 (new value)
 

var carousel = new YAHOO.widget.Carousel("container");
carousel.render();
alert(carousel.get("numVisible")); // alerts 3 (default)
carousel.set("numVisible", 1);     // override the default
alert(carousel.get("numVisible")); // alerts 1 (new value)
 

See the reference table below as well as the API documentation for Carousel Control for the complete list of configuration attributes.

Skinning the Carousel Control

Carousel comes with a default presentation or "skin," part of the "Sam Skin" visual treatment that accompanies most YUI controls. You can read more about the general approach to skinning YUI components in this in-depth article.

The CSS provided with Carousel is comprised of core, functional CSS as well as the Sam Skin visual treatment.

Reference Tables

The following tables contain information about configuration properties and CSS classes for the Carousel Widget:

• Carousel Control Configuration Attributes
• CSS classes

Known Issues

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

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out 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.