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).
jCarousel requires jQuery 1.5.0 or higher.
To use the jCarousel component, include the jQuery library, the jCarousel source file and a jCarousel skin stylesheet file inside the <head> tag of your HTML document:
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script type="text/javascript" src="/path/to/jquery.jcarousel.min.js"></script>
<link rel="stylesheet" type="text/css" href="/path/to/skin.css" />jCarousel expects a very basic HTML markup structure inside your HTML document:
<div id="mycarousel" 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 id="mycarousel" 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() {
$('#mycarousel').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[dir=rtl] li {
float: right;
}Note: These are only conventions and nothing of it is required. You can adjust the class names or the whole handling of the skinning.
If you want to provide different skins for your carousel, setup with the following markup:
<div class="jcarousel-skin-name">
<div id="mycarousel" class="jcarousel">
<ul>
<li>...</li>
<li>...</li>
</ul>
</div>
</div>We simply surround the root element with a additional <div class="jcarousel-skin-name"> to have a skin namespace. We can now style within this namespace:
.jcarousel-skin-default .jcarousel {
/* ... */
}
.jcarousel-skin-default .jcarousel ul {
/* ... */
}
.jcarousel-skin-default .jcarousel li {
/* ... */
}The download package contains some example skin packages. Feel free to build your own skins based on it.
Note: Skins will follow!
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. |
| 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 way to navigate through the carousel (scroll prev, next or to a specific position).
You can do that by hand (see "Accessing the jCarousel instance" for available methods) or use a plugin for that.
A simple example to navigate the carousel:
$('#mycarousel_prev_button').click(function() {
$('#mycarousel').jcarousel('scrollBy', -1);
});
$('#mycarousel_next_button').click(function() {
$('#mycarousel').jcarousel('scrollBy', 1);
});A more comfortable way is to use one of the navigation plugins:
- jquery.jcarousel.buttons.js
- jquery.jcarousel.pagination.js
Note: Plugins will follow!
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 skin 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:
$('#mycarousel').jcarousel({vertical: true});Alternatively, you can simply use a class for your root element which contains the string jcarousel-vertical:
<div class="jcarousel-skin-name">
<div id="mycarousel" class="jcarousel-vertical">
<ul>
<!-- The content goes in here -->
</ul>
</div>
</div>To create a carousel in RTL mode, set the rtl option to true:
$('#mycarousel').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-skin-name">
<div id="mycarousel" class="jcarousel" dir="rtl">
<ul>
<!-- The content goes in here -->
</ul>
</div>
</div>If you have created a carousel like:
$(function() {
$('#mycarousel').jcarousel();
});You can later access the jCarousel instance with:
var jcarousel = $('#mycarousel').data('jcarousel');
// Call a method
jcarousel.scrollTo(2);Methods can be also called directly like this:
$('#mycarousel').jcarousel('scrollTo', 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('scrollBy', offset [, animate [, callback]]); |
Scrolls by a given offset (offset can be negative to scroll backwards). If callback is given and a valid callback, it is triggered after the animation is finished. |
.jcarousel('scrollTo', item_or_index [, animate [, callback]]); |
Scrolls to a given item or index. 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. |
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() {
$('#mycarousel').jcarousel({
// Configuration goes here
});
// Append items
$('#mycarousel ul')
.append('<li>Item 1</li>')
.append('<li>Item 2</li>');
// Reload carousel
$('#mycarousel').jcarousel('reload');
});After initialization, jCarousel triggers specific events on the root element and the items of the carousel.
| Event | Description | Example |
|---|---|---|
| jcarouselsetup | Triggered when the setup method is called. |
$('#mycarousel').bind('jcarouselsetup', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
| jcarouselsetupend | Triggered after the setup method is called. |
$('#mycarousel').bind('jcarouselsetupend', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
| jcarouselreload | Triggered when the reload method is called. |
$('#mycarousel').bind('jcarouselreload', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
| jcarouselreloadend | Triggered after the reload method is called. |
$('#mycarousel').bind('jcarouselreload', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
| jcarouseldestroy | Triggered when the destroy method is called. |
$('#mycarousel').bind('jcarouseldestroy', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
| jcarouseldestroyend | Triggered after the destroy method is called. |
$('#mycarousel').bind('jcarouseldestroyend', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
| jcarouselscrollby | Triggered when the scrollBy method is called. |
$('#mycarousel').bind('jcarouselscrollby', function(carousel, offset, animate) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
// "offset" is the offset jCarousel was requested to scroll by
// "animate" is a boolean indicating whether jCarousel was requested to do an animation
});
|
| jcarouselscrollbyend | Triggered after the scrollBy method is called. |
$('#mycarousel').bind('jcarouselscrollbyend', function(carousel, animated) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
// "animated" is a boolean indicating whether jCarousel actually moved
});
|
| jcarouselscrollto | Triggered when the scrollTo method is called. |
$('#mycarousel').bind('jcarouselscrollto', function(carousel, item, animate) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
// "item" is the item jCarousel was requested to scroll to. This can be either an object or an integer.
// "animate" is a boolean indicating whether jCarousel was requested to do an animation
});
|
| jcarouselscrolltoend | Triggered after the scrollTo method is called. |
$('#mycarousel').bind('jcarouselscrolltoend', function(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. |
$('#mycarousel').bind('jcarouselanimate', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
| jcarouselscrolltoend | Triggered after jCarousel has finished a animation. |
$('#mycarousel').bind('jcarouselanimateend', function(carousel) {
// "this" refers to the root element
// "carousel" is the jCarousel instance
});
|
Note: Some events like jcarouselsetup are triggered from the constructor, so you have to bind the events before you initialize the carousel:
$('#mycarousel')
// Bind first
.bind('jcarouselsetup', function(carousel) {
// Do something
})
// Initialize at last step
.jcarousel();| Event | Description | Example |
|---|---|---|
| jcarouselitemfirstin | Triggered when the item becomes the first visible item. |
$('#mycarousel li').bind('jcarouselitemfirstin', function(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. |
$('#mycarousel li').bind('jcarouselitemfirstout', function(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. |
$('#mycarousel li').bind('jcarouselitemlastin', function(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. |
$('#mycarousel li').bind('jcarouselitemlastout', function(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. |
$('#mycarousel li').bind('jcarouselitemvisiblein', function(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. |
$('#mycarousel li').bind('jcarouselitemvisibleout', function(carousel) {
// This is no longer a visible item
// "this" refers to the item element
// "carousel" is the jCarousel instance
});
|
After initialization, you can use jCarousel specific selectors on the root element and on the items of the carousel.
| Selector | Description | Example |
|---|---|---|
| :jcarousel | Selects elements which have a initialized jcarousel instance applied. | $(':jcarousel'); |
| Selector | Description | Example |
|---|---|---|
| :jcarousel-item-first | Selects the first visible element. | $('#mycarousel :jcarousel-item-first'); |
| :jcarousel-item-last | Selects the last visible element. | $('#mycarousel :jcarousel-item-last'); |
| :jcarousel-item-visible | Selects all visible elements. | $('#mycarousel :jcarousel-item-visible'); |
jCarousel is written on top of jQuery and is inspired by the Carousel Component by Bill Scott.