/jcarousel

Riding carousels with jQuery.

Primary LanguageJavaScript

jCarousel - Riding carousels with jQuery

jCarousel is a jQuery plugin for controlling a list of items in horizontal or vertical order. The items, which can be static HTML content or loaded with (or without) AJAX, can be scrolled back and forth (with or without animation).

Note: The master branch contains the new version 0.3 which is not released yet and is not compatible with 0.2.

Getting started

To use the jCarousel component, include the jQuery library and the jCarousel source file inside the <head> tag of your HTML document:

<link rel="stylesheet" type="text/css" href="/path/to/jcarousel.css" />
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script type="text/javascript" src="/path/to/jquery.jcarousel.js"></script>

jCarousel expects a very basic HTML markup structure inside your HTML document:

<div class="jcarousel">
    <ul>
        <li>...</li>
        <li>...</li>
    </ul>
</div>

This document refers to the elements as root element, list element and item element(s):

<div class="jcarousel"> <----------------------------------| Root element
    <ul> <--------------------------------| List element   |
        <li>...</li> <---| Item element   |                |
        <li>...</li> <---| Item element   |                |
    </ul> <-------------------------------|                |
</div> <---------------------------------------------------|

To setup jCarousel, add the following code inside the <head> tag of your HTML document:

<script type="text/javascript">
$(function() {
    $('.jcarousel').jcarousel({
        // Configuration goes here
    });
});
</script>

These are the minimal CSS settings for a horizontal carousel:

.jcarousel {
    position: relative;
    overflow: hidden;
}

.jcarousel ul {
    width: 20000em;
    position: absolute;
    list-style: none;
    margin: 0;
    padding: 0;
}

.jcarousel li {
    float: left;
}

Configuration

jCarousel accepts a list of options to control the behaviour of the carousel. Here is the list of options you may set:

Property Type Default Description
list string ">ul:eq(0)" jQuery selector to select the list inside the root element.
items string ">li" jQuery selector to select the items inside the list element.
animation integer|string|object "normal" The speed of the scroll animation as string in jQuery terms ("slow" or "fast") or milliseconds as integer (See the jQuery Documentation). If set to 0, animation is turned off. Alternatively, this can be a map of options like the one jQuery.animate accepts as second argument or a function. A function will be called in the context of the carousel instance and with 2 arguments: The first is a hash of css properties (ie. {left: -400}) and the second is a function which must be called as a callback.
wrap string null Specifies whether to wrap at the first/last item (or both) and jump back to the start/end. Options are "first", "last", "both" or "circular" as string. If set to null, wrapping is turned off (default).
vertical boolean null Specifies whether the carousel appears in vertical orientation. Changes the carousel from a left/right style to a up/down style carousel. If not set, jCarousel looks for a class jcarousel-vertical on the root element and if found, automatically sets vertical to true.
rtl boolean null Specifies wether the carousel appears in RTL (Right-To-Left) mode. If not set, jCarousel looks for dir attribute with a value of rtl on the root element (or to any of its parent elements) and if found, automatically sets rtl to true.
center boolean false Specifies wether the carousel should be centered inside the root element. Note: This feature is experimental and may not work with all carousel setups.

Navigating the carousel

By default, jCarousel offers no built in controls to navigate through the carousel. But you can simply implement navigation controls using the scroll method.

$('.jcarousel').jcarousel('scroll', target);

Available formats for the target argument are:

Format Description Example
index Scrolls to the item at the given index (Note that indexes are 0-based).
$('.jcarousel').jcarousel('scroll', 0);
-index Scrolls to the item at the given index counting backwards from the last item.
$('.jcarousel').jcarousel('scroll', -1);
object Scrolls to the given DOM object.
$('.jcarousel').jcarousel('scroll', $('.jcarousel li:eq(2)'));
+=offset Scrolls the carousel forward by the given offset relatively from the current position.
$('.jcarousel').jcarousel('scroll', '+=1');
-=offset Scrolls the carousel backwards by the given offset relatively from the current position.
$('.jcarousel').jcarousel('scroll', '-=1');

A simple example for previous and next controls:

$('.jcarousel-prev').click(function() {
    $('.jcarousel').jcarousel('scroll', '-=1');
});

$('.jcarousel-next').click(function() {
    $('.jcarousel').jcarousel('scroll', '+=1');
});

A more comfortable way is to use a navigation plugins:

Defining the number of visible items

Sometimes people are confused how to define the number of visible items because there is no option for this as they expect.

You simply define the number of visible items by defining the width (or height for a vertical carousel) of the element which surrounds the list (if you use the default from this document, you do that with the class .jcarousel in your stylesheet).

This offers a lot of flexibility, because you can define the width in pixel for a fixed carousel or in percent for a flexible carousel.

Vertical carousels

To create a vertical carousel, set the vertical option to true:

$('.jcarousel').jcarousel({vertical: true});

Alternatively, you can simply use a class for your root element which contains the string jcarousel-vertical:

<div class="jcarousel jcarousel-vertical">
    <ul>
        <!-- The content goes in here -->
    </ul>
</div>

RTL (Right-To-Left) carousels

To create a carousel in RTL mode, set the rtl option to true:

$('.jcarousel').jcarousel({rtl: true});

Alternatively, you can simply add the dir attribute with a value of rtl to the root element (or to any of its parent elements):

<div class="jcarousel" dir="rtl">
    <ul>
        <!-- The content goes in here -->
    </ul>
</div>

You should also add the following to your CSS stylesheet:

.jcarousel[dir=rtl] li {
    float: right;
}

Accessing the jCarousel instance

If you have created a carousel like:

$(function() {
    $('.jcarousel').jcarousel();
});

You can later access the jCarousel instance with:

var jcarousel = $('.jcarousel').data('jcarousel');

// Call a method
jcarousel.scroll('+=2');

Methods can be also called directly like this:

$('.jcarousel').jcarousel('scroll', '+=2');

The first argument is the method name. The following arguments are the arguments for the called method.

Available methods are:

Method Description
.jcarousel('destroy');
Removes the jCarousel functionality completely. This will return the element back to its pre-init state.
.jcarousel('reload');
Reloads the carousel. This method is useful to reinitialize the carousel if you have changed the content of the list from the outside.
.jcarousel('items');
Returns all items as jQuery object.
.jcarousel('scroll', target [, animate [, callback]]);
Scrolls to a specific item or relative by a given offset (See section "Navigating the carousel" for more information about the target argument). If the argument animate is given and false, it just jumps to the position without animation. If callback is given and a valid callback, it is triggered after the animation is finished.
.jcarousel('option', name, [value]);
Get or set any jCarousel option. If no value is specified, will act as a getter.
.jcarousel('option', options);
Set multiple jCarousel options at once by providing an options object.
.jcarousel('option', callback);
Set multiple jCarousel options by passing a function which returns an options object. The function is executed in the context of the carousel instance.

Manipulating the carousel

If you manipulate the carousel from the outside (eg. adding or removing items from the list), ensure that you call reload() afterwards so that jCarousel becomes aware of the changes:

$(function() {
    $('.jcarousel').jcarousel({
        // Configuration goes here
    });

    // Append items
    $('.jcarousel ul')
        .append('<li>Item 1</li>')
        .append('<li>Item 2</li>');

    // Reload carousel
    $('.jcarousel').jcarousel('reload');
});

Existing items should only be manipulated not completely replaced:

$(function() {
    // Don't do that
    $('.jcarousel li:eq(0)')
        .replaceWith('<li class="myclass">Item 1</li>');

    // Do this
    $('.jcarousel li:eq(0)')
        .addClass('myclass')
        .text('Item 1');
});

If you are removing items, make sure they are currently not visible:

$(function() {
    var carousel = $('.jcarousel'),
        item = carousel.find('li:eq(0)');

    if (carousel.jcarousel('visible').index(items) < 0) {
        item.remove();
        carousel.jcarousel('reload');
    }
});

jCarousel specific events

After initialization, jCarousel triggers specific events on the root element and the items of the carousel.

Available root element events are:

Event Description Example
jcarouselinit Triggered on initialization of the carousel.
$('.jcarousel').bind('jcarouselinit', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});
jcarouselinitend Triggered after initialization of the carousel.
$('.jcarousel').bind('jcarouselinitend', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});
jcarouselreload Triggered when the reload method is called.
$('.jcarousel').bind('jcarouselreload', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});
jcarouselreloadend Triggered after the reload method is called.
$('.jcarousel').bind('jcarouselreload', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});
jcarouseldestroy Triggered when the destroy method is called.
$('.jcarousel').bind('jcarouseldestroy', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});
jcarouseldestroyend Triggered after the destroy method is called.
$('.jcarousel').bind('jcarouseldestroyend', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});
jcarouselscroll Triggered when the scroll method is called.
$('.jcarousel').bind('jcarouselscroll', function(event, carousel, target, animate) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
    // "target" is the target argument passed to the `scroll` method
    // "animate" is the animate argument passed to the `scroll` method 
    //      indicating whether jCarousel was requested to do an animation
});
jcarouselscrollend Triggered after the scroll method is called. Note that this method is triggered at the end of the scroll method and not at the end of a animation.
$('.jcarousel').bind('jcarouselscrollend', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
    // "animated" is a boolean indicating whether jCarousel actually moved
});
jcarouselanimate Triggered when jCarousel starts a animation.
$('.jcarousel').bind('jcarouselanimate', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});
jcarouselanimateend Triggered after jCarousel has finished a animation.
$('.jcarousel').bind('jcarouselanimateend', function(event, carousel) {
    // "this" refers to the root element
    // "carousel" is the jCarousel instance
});

Note: Some events like jcarouselinit are triggered from the constructor, so you have to bind the events before you initialize the carousel:

$('.jcarousel')

    // Bind first
    .bind('jcarouselinit', function(event, carousel) {
        // Do something
    })

    // Initialize at last step
    .jcarousel();

Available item events are:

Event Description Example
jcarouselitemfirstin Triggered when the item becomes the first visible item.
$('.jcarousel li').bind('jcarouselitemfirstin', function(event, carousel) {
    // This is now the first visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});
jcarouselitemfirstout Triggered when the item is no longer the first visible item.
$('.jcarousel li').bind('jcarouselitemfirstout', function(event, carousel) {
    // This is no longer the first visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});
jcarouselitemlastin Triggered when the item becomes the last visible item.
$('.jcarousel li').bind('jcarouselitemlastin', function(event, carousel) {
    // This is now the last visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});
jcarouselitemlastout Triggered when the item is no longer the last visible item.
$('.jcarousel li').bind('jcarouselitemlastout', function(event, carousel) {
    // This is no longer the last visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});
jcarouselitemvisiblein Triggered when the item becomes a visible item.
$('.jcarousel li').bind('jcarouselitemvisiblein', function(event, carousel) {
    // This is now a visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});
jcarouselitemvisibleout Triggered when the item is no longer a visible item.
$('.jcarousel li').bind('jcarouselitemvisibleout', function(event, carousel) {
    // This is no longer a visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});
jcarouselitemfullyvisiblein Triggered when the item becomes a fully visible item.
$('.jcarousel li').bind('jcarouselitemfullyvisiblein', function(event, carousel) {
    // This is now a fully visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});
jcarouselitemfullyvisibleout Triggered when the item is no longer a fully visible item.
$('.jcarousel li').bind('jcarouselitemfullyvisibleout', function(event, carousel) {
    // This is no longer a fully visible item
    // "this" refers to the item element
    // "carousel" is the jCarousel instance
});

jCarousel specific classes

jCarousel adds specific classes to the carousel items indicating their current status.

This is useful for selecting items on runtime or add specific styling to them.

Class Description Example
.jcarousel-item-target Indicates the targeted item.
$('.jcarousel .jcarousel-item-target');
.jcarousel-item-first Indicates the first visible item.
$('.jcarousel .jcarousel-item-first');
.jcarousel-item-last Indicates the last visible item.
$('.jcarousel .jcarousel-item-last');
.jcarousel-item-visible Indicates a visible items.
$('.jcarousel .jcarousel-item-visible');
.jcarousel-item-fullyvisible Indicates a fully visible items.
$('.jcarousel .jcarousel-item-fullyvisible');

Credits

jCarousel is written on top of jQuery and was originally inspired by the Carousel Component by Bill Scott.