By Karl Swedberg, based on the original by Ganeshji Marwaha.
This jQuery plugin creates a carousel-style navigation widget for images, or any content, from simple HTML markup.
The HTML markup to build the carousel can be as simple as the following:
<div class="carousel">
<ul>
<li><img src="image/1.jpg" alt="1"></li>
<li><img src="image/2.jpg" alt="2"></li>
<li><img src="image/3.jpg" alt="3"></li>
</ul>
</div>This snippet is nothing but a simple div containing an unordered list of images. The "carousel" class for the div here is just for the sake of explanation. You can use any class — or none at all — for any of the elements.
To manually navigate the elements of the carousel, you can include some kind of navigation buttons.
For example, you can have a "previous" button to go backward and a "next" button to go forward.
They need not be part of the carousel div itself; they can be any element in your document.
For example, let's assume you want the following elements to be used as prev and next buttons:
<button class='prev'> » </button>
<button class='next'> « </button>With the default settings, the carousel probably needs only a single CSS rule in your stylesheet
(again, using <div class="carousel"> as our example):
div.carousel {
overflow: hidden;
}All you need to do is call the carousel component on the div element that represents it and pass in the
navigation buttons as options.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev'
});There are quite a few other settings that you can use to customize it. Each will be explained with an example below.
You can specify all the options shown below as object properties.
New as of jCarouselLite 1.9. Allows the "ul" container to be customized using any valid selector expression to match elements against. The plugin will use the first element within the carousel div that matches the selector.
$('div.carousel').jCarouselLite({
containerSelector: '.my-slide-container'
});New as of jCarouselLite 1.9. Allows the "li" slides to be customized using any valid selector expression to match elements against. The plugin will use elements that match the itemSelector string and are direct children of the containerSelector.
$('div.carousel').jCarouselLite({
itemSelector: '.my-slide'
});New as of jCarouselLite 1.8. Allows the height and width of the carousel and its list items to be reset when the window size changes (if autoCSS and/or autoWidth set to true). Adds an event handler on the window resize event that triggers the refreshCarousel custom event when the window stops being resized. See Responsive Carousels for more information.
New as of jCarouselLite 1.8. Enables the carousel to respond to touch input — namely single-touch swiping motions.
New as of jCarouselLite 1.8 The three swipeThresholds properties refer to movement along the x and y axes (in pixels) and the duration of that movement (in milliseconds) from touch start to touch end. The combination of these properties determine when a directional swipe has occurred and, thus, when the carousel should scroll.
When true (default), prevents vertical scrolling of the document window when swiping on a horizontal carousel.
Creates a basic carousel. Clicking "btnPrev" navigates backwards and "btnNext" navigates forward.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev'
});You can use the btnGo option along with the btnNext / btnPrev buttons or instead of them.
If you supply an array, the index of each item in the array represents the index of the element in the carousel. In other words, if the first element in the array is ".one," then clicking the element represented by ".one" will slide the carousel to the first element.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
btnGo: ['.one', '.two', '.three']
});In the following example, clicking a link within #carousel-nav will slide the carousel to the item with an index matching the link's index among the other links.
$('div.carousel').jCarouselLite({
btnGo: $('#carousel-nav a')
});When the autoCSS option is set to false, the plugin does not set any of the initial styles on the carousel elements, allowing you to apply these styles (or a subset of them) yourself in a stylesheet.
$('div.carousel').jCarouselLite({
autoCSS: false
});The following is a generic example of styles set by the plugin when the default autoCSS: true is used.
/* the selectors here (div, ul, li) are meant only for example.
you would, of course, use more specific selectors
to target your actual carousel elements */
div {
visibility: visible;
position: relative;
z-index: 2;
/* if the vertical option is set to true, the following would be height */
width: XXX /* calculated: width of the first li * number of visible items */;
}
ul {
margin: 0;
padding: 0;
position: relative;
list-style-type: none;
z-index: 1;
/* if the vertical option is set to true, the following would be height */
/* can be any number larger than total combined width of list items */
width: XXX /* calculated: width of the first li * total number of list items */;
/* if the vertical option is set to true, the following would be margin-top */
margin-left: -XXX /* calculdated: -starting item * width of first li */;
}
li {
overflow: visible /* if vertical: true, overflow is hidden */;
float: left /* if vertical: true, float is none */;
width: XXX /*calculated: width of the first li */
height: XXX /*calculated: height of the first li */
}When the autoWidth option is set to true, the plugin sets the width of
the <li>s and left/top of the <ul> based on the width of the <div>
The btnDisabledClass value is automatically added to the btnPrev or btnNext element when a non-circular carousel is at the first or last slide, respectively.
The activeClass value is automatically added to the active slide's class. This allows customized animations within the beforeStart and beforeEnd callback options.
When the btnGo option is set, the element in the btnGo set that corresponds to the first currently visible carousel item will have a class added to it. The default activeClass is "active," but this can be overridden as shown in the following example:
$('div.carousel').jCarouselLite({
btnGo: $('#carousel-nav a'),
visible: 2,
activeClass: 'current'
});When the btnGo option is set, the element in the btnGo set that corresponds to the currently visible carousel item(s) will have a class added to them. The default visibleClass is "vis," but this can be overridden as shown in the following example:
$('div.carousel').jCarouselLite({
btnGo: $('#carousel-nav a'),
visible: 2,
visibleClass: 'highlight'
});The carousel will navigate by itself if this option is set to true or a number greater than 0. If true, the carousel will scroll by the number of slides indicated by the scroll option (default is 1). If a positive number, it will auto-scroll by that number instead, although clicks on the previous/next button will still cause it to scroll by the scroll option's number.
$('div.carousel').jCarouselLite({
auto: true,
speed: 500
});$('div.carousel').jCarouselLite({
auto: 2,
scroll: 1,
visible: 2,
btnNext: '.next',
btnPrev: '.prev'
});If the directional option is set to true, autoscrolling changes direction when the user clicks the "previous" or "next" button
When the auto option is set to true (or a number greater than 0), the carousel automatically transitions after the amount of time specified by the timeout option.
$('div.carousel').jCarouselLite({
auto: true,
timeout: 8000
});Specifying a speed will slow down or speed up the sliding speed of your carousel. Providing 0 will remove the slide effect.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
speed: 800
});The default easing of jQuery core, "swing," is used if no easing is specified in the options. You will need an easing plugin if you wish to specify an easing effect other than jQuery's own "swing" or "linear."
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
easing: 'bounceout'
});Determines the direction of the carousel. If set to true, the carousel will display vertically; the next and
prev buttons will slide the items vertically as well. The default is false, which means that the carousel will
display horizontally. The next and prev buttons will slide the items from left to right in this case.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
vertical: true
});Setting it to true enables circular navigation. This means, if you click "next" after you reach the last
element, you will automatically slide to the first element and vice versa. If you set circular to false, then
if you click on the "next" button after you reach the last element, you will stay in the last element itself
and similarly for "previous" button and first element.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
circular: false
});This specifies the number of items visible at all times within the carousel. The default is 3.
You may set this option to a fractional number (such as 3.5), as well.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
visible: 4
});You can specify from which item the carousel should start. Remember, the first item in the carousel has a start of 0, and so on.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
// start on the *third* item
start: 2
});The number of items that should scroll/slide when you click the next/prev navigation buttons. By
default, only one item is scrolled, but you may set it to any number. For example, setting it to 2 will scroll
2 items when you click the next or previous buttons.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
scroll: 2
});The carousel can also be navigated using the mouse wheel interface of a scroll mouse instead of (or in addition to) using buttons. To enable this feature, you have to do 2 things:
- include the mouse-wheel plugin from Brandon Aaron (http://github.com/brandonaaron/).
- set the option "mouseWheel" to true.
$('div.carousel').jCarouselLite({
mouseWheel: true
});To use the previous/next buttons as well as the scroll wheel, just supply the options required for both:
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
mouseWheel: true
});The init callback function allows you to do some logic for each carousel div before any of the carousel behavior and styles are applied to it. The function will be passed two arguments:
- Object representing the result of merging the default settings with the options object passed in when calling .jCarousellite()
- jQuery Object containing the top-level
<li>elements in the carousel (useful for checking their length against number of items to be visible at once)
If the function returns false, the plugin will skip all the carousel magic for that carousel <div>.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
init: function(opts, $lis) {
if ($lis.length > opts.visible) {
$('div.carousel').append('<a class="prevnext prev">previous</a> <a class="prevnext next">next</a>');
} else {
return false;
}
}
});When the circular option is set to false you have the option of doing something once the first or last slide has been reached via callbacks.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
first: function() {
alert('This is the first slide');
},
last: function() {
alert('This is the last slide');
}
});If you want to do some logic before the slide starts and after the slide ends,
you can register these 2 callbacks. Inside the functions, this is the
div on which the .jCarouselLite() method is called.
The functions will be passed three arguments:
- Array of elements that are visible at the time of callback.
- Boolean indicating whether the direction is forward (
true) or backward (false); - Object containing information that differs depending on what triggered the advance. If triggered by clicking one of the
btnGoelements, for example, the object has two properties:btnGo, which references the clicked DOM element, andbtnGoIndex, presenting the index of the clicked DOM element in relation to the other "btnGo" buttons.
$('div.carousel').jCarouselLite({
btnNext: '.next',
btnPrev: '.prev',
beforeStart: function(a, direction) {
alert('Before animation starts:' + a);
},
afterEnd: function(a, direction) {
alert('After animation ends:' + a);
}
});The plugin binds a few custom event handlers to the wrapping div element. They can be triggered at any time by using jQuery's event triggering mechanism. If other custom events are bound to the same elements, you may wish to trigger these using the .jc namespace. For example, instead of .trigger("pauseCarousel"), you could write .trigger("pauseCarousel.jc").
Pauses an autoscrolling carousel until resumeCarousel is triggered. Note: if the pause option is set to true, then the resumeCarousel event is automatically triggered when the mouse leaves the carousel div.
$('div.carousel').trigger('pauseCarousel')Resumes an autoscrolling carousel after having been paused.
$('div.carousel').trigger('resumeCarousel')Stops an autoscrolling carousel in a similar fashion to pauseCarousel, with the exception that resumeCarousel will NOT resume the carousel, and neither will the mouse leaving the carousel div. To resume automatic movement on the carousel, use startCarousel.
$('div.carousel').trigger('stopCarousel')Stops the carousel from functioning and removes all events and data bound by the plugin.
Updates the dimensions of the carousel and, optionally (as of 1.9.1), the plugin's record of items being used in the carousel. When the responsive option is set to true, the refreshCarousel event is triggered automatically when the window stop resizing (it is "debounced" so it doesn't occur repeatedly during resize).
// Insert a slide into the carousel.
// Then...
$('div.carousel').trigger('refreshCarousel', '[all]')To get a better sense of dynamically adding slides to a carousel, see this example of refreshCarousel
$('div.carousel').trigger('endCarousel')When triggering the go custom event, you can pass in an integer representing the item in the carousel to go to.
$('div.carousel').trigger('go', 3)You may also pass in a string ("+=n" or "-=n") to specify an item relative to the currently active item.
$('div.carousel').trigger('go', '+=2')The default is "+=1" (i.e. the next item).
$('div.carousel').trigger('go')The responsive option is set to false by default. Once you set it to true,
you may want to set a few other options to get the desired effect:
$('div.carousel').jCarouselLite({
// autoCSS: true,
autoWidth: true,
responsive: true
});Your best bet in this situation is to use CSS media queries.
$('div.carousel').jCarouselLite({
autoCSS: false,
// autoWidth: false,
responsive: true
});
// Bind your own handler to the `refreshCarousel` custom event,
// which is triggered when the window stops resizing
$('div.carousel').on('refreshCarousel', function() {
// do something
});