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.7.0/build/carousel/assets/skins/sam/carousel.css">

                <!-- Dependencies --> 
                <script type="text/javascript" src="http://yui.yahooapis.com/2.7.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
                <script type="text/javascript" src="http://yui.yahooapis.com/2.7.0/build/element/element-min.js"></script>

                <!-- Optional: Animation library for animating the scrolling of items --> 
                <script type="text/javascript" src="http://yui.yahooapis.com/2.7.0/build/animation/animation-min.js"></script>
                <!-- Optional: Connection library for dynamically loading items --> 
                <script type="text/javascript" src="http://yui.yahooapis.com/2.7.0/build/connection/connection-min.js"></script>

                <!-- Source file --> 
                <script type="text/javascript" src="http://yui.yahooapis.com/2.7.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 <ol> or <ul>.

                <div id="container">
                 <ul>
                <li><img alt="" src="..."></li>
                ...
                </ul>
                </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
                

Using no existing HTML

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

                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("container"); // render the widget inside the
                                              // container 
                carousel.show(); // display the widget
                

While calling the render method when the Carousel is constructed from JavaScript, the id attribute of the parent container that would contain the widget needs to be passed to it.

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>
                

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.show();
                    // rest of the code
                });
                

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.

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.show();
                

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

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

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 autoPlay configuration setting. The following example illustrates setting this property and also making the Carousel circular.

                var carousel = new YAHOO.widget.Carousel("container");
                carousel.set("autoPlay", 2000);   // automatically scroll every
                                                  // two seconds
                carousel.set("isCircular", true); // make the widget circular
                carousel.show();
                

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

                var carousel = new YAHOO.widget.Carousel("container", {
                    autoPlay: 2000, isCircular: true
                });
                carousel.show();
                

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.show();
                

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

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

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.show();
                

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

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

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.show();
                

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("beforeScrollEvent", function (obj) {
                    // obj contains the following information:
                    // {
                    //    first: firstVisibleIndex,
                    //    last: lastVisibleIndex,
                    //    dir: direction of scroll
                    // }
                });
                carousel.show();
                

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.show();

                function scrollEvtHandler(obj) {
                    // ...
                }
                
                carousel.addListener("beforeScrollEvent", scrollEvtHandler);
                // ...
                carousel.removeListener("beforeScrollEvent", 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.show();
                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 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 YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.