Submit your widget

jcarousellite - A jQuery carousel plugin based on jCarouselLite by Ganeshji Marwaha

Created 4 years ago   Views 2961   downloads 811    Author kswedberg
View DemoDownload
20
Share |

jCarouselLite

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. Check out a bare-bones demo.

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'> &raquo; </button>
<button class='next'> &laquo; </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.

Options

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.

$