This jQuery plugin creates a carousel-style navigation widget for images, or any content, from simple HTML markup. Check out a bare-bones demo.
The HTML markup to build the carousel can be as simple as the following:
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:
With the default settings, the carousel probably needs only a single CSS rule in your stylesheet
<div class="carousel"> as our example):
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.
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.
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
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
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.
You can use the
btnGo option along with the
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.
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.
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.
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 selectorsto target your actual carousel elements */
autoWidth option is set to
true, the plugin sets the width of
<li>s and left/top of the
<ul> based on the width of the
btnDisabledClass value is automatically added to the
btnNext element when a non-circular carousel is at the first or last slide, respectively.
activeClass value is automatically added to the active slide's class. This allows customized animations within the
beforeEnd callback options.
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:
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:
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.
directional option is set to
true, autoscrolling changes direction when the user clicks the "previous" or "next" button
auto option is set to
true (or a number greater than 0), the carousel automatically transitions after the amount of time specified by the
Specifying a speed will slow down or speed up the sliding speed of your carousel. Providing 0 will remove the slide effect.
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."
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.
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.
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.
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.
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.
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:
To use the previous/next buttons as well as the scroll wheel, just supply the options required for both:
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:
<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
circular option is set to false you have the option of doing something once the first or last slide has been reached via callbacks.
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 two arguments:
true) or backward (
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
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.
Resumes an autoscrolling carousel after having been paused.
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
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
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...
To get a better sense of dynamically adding slides to a carousel, see this example of
When triggering the
go custom event, you can pass in an integer representing the item in the carousel to go to.
You may also pass in a string ("+=n" or "-=n") to specify an item relative to the currently active item.
The default is "+=1" (i.e. the next item).
responsive option is set to
false by default. Once you set it to
you may want to set a few other options to get the desired effect:
Your best bet in this situation is to use CSS media queries.
;// Bind your own handler to the `refreshCarousel` custom event,// which is triggered when the window stops resizing;