Usage

• Calling methods on the jCarousel instance
• Navigating the carousel
• Defining the number of visible items
• Vertical carousels
• RTL (Right-To-Left) carousels
• Manipulating the carousel

Calling methods on the jCarousel instance

If you have created a carousel like:

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

You can later call methods on the jCarousel instance like:

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

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

Alternatively, you can first grab the jCarousel instance and call the methods directly on it:

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

instance.scroll('+=2');

See API for all available methods.

Navigating the carousel

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);

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 plugin:

• Control Plugin
• Pagination Plugin

Defining the number of visible items

You simply define the number of visible items by defining the width (or height for a vertical carousel) of the root element (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.

Fixed carousel

Always 3 visible items:

.jcarousel {
    position: relative;
    overflow: hidden;
    width: 300px;
}

.jcarousel li {
    float: left;
    width: 100px;
}

Flexible carousel

The number of visible items depend on the width of the root's parent element:

.jcarousel {
    position: relative;
    overflow: hidden;
    width: 100%;
}

.jcarousel li {
    float: left;
    width: 100px;
}

Vertical carousels

jCarousel tries to auto-detect the orientation by simply checking if the list elements’s height is greater than the list element’s width.

If auto-detection doesn't work, you can explicitly pass the vertical option:

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

RTL (Right-To-Left) carousels

jCarousel tries to auto-detect if the carousel should run in RTL mode by looking for a dir attribute with the value rtl on the root or any of its parent elements.

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

If auto-detection doesn't work, you can explicitly pass the rtl option. Note: The dir="rtl" attribute is still required!

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

When running a carousel in RTL mode, you should ensure to float the items to the right:

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

Manipulating the carousel

If you manipulate the carousel from the outside (eg. adding or removing items from the list), ensure that you call the reload method 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(item) < 0) {
        item.remove();
        carousel.jcarousel('reload');
    }
});