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.
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;
}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. |
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:
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.
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>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;
}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.
| 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. |
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');
}
});After initialization, jCarousel triggers specific events on the root element and the items of the carousel.
| 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();| 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 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'); |
jCarousel is written on top of jQuery and was originally inspired by the Carousel Component by Bill Scott.