jCarousel Lite – A jQuery plugin

jcarousellite-img-02

jCarousel Lite is a jQuery plugin that carries you on a carousel ride filled with images and HTML content. Put simply, you can navigate images and/or HTML in a carousel-style widget. It is super light weight, at about 2 KB in size, yet very flexible and customizable to fit most of our needs.

Did I mention that it weighs just 2 KB?

As if that wasn’t enough, the best part is yet to come… You don’t need any special css file or class name to get this to work. Include the js file. Supply the HTML markup. Then, construct the carousel with just a simple function call.

Visit the project page for more information. There you can find a lot of demos and exhaustive documentation. This blog entry is just a teaser for further exploration.

Installing and getting it to work is as trivial as following the 3 steps given below…

Step 1:

Include a reference to the jQuery library and the jCarouselLite plugin. You can download jQuery here and jCarouselLite here. If you like interesting effects, include the Easing plugin as well (Optional). You may also want to use a compatibility easing plugin if you want to use old easing names. If you would like to navigate the carousel using mouse wheel, then include the mouse-wheel plugin as well (Optional).

<script type="text/javascript" src="path/to/jquery.js"></script>
<script type="text/javascript" src="path/to/jquery.jcarousellite.js"></script>

<!-- Optional -->
<script type="text/javascript" src="path/to/easing.js"></script>
<script type="text/javascript" src="path/to/mousewheel.js"></script>

Step 2:

In your HTML file, provide the markup required by the carousel (a div enclosing an ul). You also need the navigation buttons, but these buttons need not be part of the carousel markup itself. An example follows…

<button class="prev">&laquo;</button>
<button class="next">&raquo;</button>

<div class="any-class">
    <ul>
        <li><img src="image/1.jpg" style="width:150px; height:118px;"></li>
        <li><img src="image/2.jpg" style="width:150px; height:118px;"></li>
        <li><img src="image/3.jpg" style="width:150px; height:118px;"></li>
        <li><img src="image/4.jpg" style="width:150px; height:118px;"></li>
        <li><img src="image/5.jpg" style="width:150px; height:118px;"></li>
    </ul>
</div>

Step 3:

Fire a call to the plugin and supply your navigation buttons. You just managed to architect your own carousel.

$(function() {
    $(".any-class").jCarouselLite({
        btnNext: ".next",
        btnPrev: ".prev"
    });
});

If you have any comments/suggestions/requests, feel free to drop in a comment or reach @ganeshmax in twitter.

 

Update

Based on popular request, jCarouselLite has been updated to support jquery 1.2.x versions. Goto the download page and download version 1.0.1 to enjoy jquery 1.2.x support. Since Firefox 3 has some issues with $(document).ready() function, try using $(window).load() instead if you face any problems. Hopefully a future version of Firefox or jQuery will fix the problem.

Ganeshji Marwaha

I spend my days as the Director of Technology for Mobility practice and help my clients design enterprise and consumer mobile strategies. Mobile Payments, Digital Wallet and Tokenization technologies are my areas of specialization

  • Matt

    Hi,

    Great plugin!

    I’m using a Bubble Up effect (not a plugin, just animation with a z-index of 100) on images in the carousel and it’s not displaying the images past the pre-set size (it should put the image up and to the right). I was previously using a toggle to change between 2 divs, but needed a carousel to add more list items.

    Is there a way to over-ride the image being a set size and not applying the overflow?

    Thanks,
    Matt

  • S.P.

    Thanks for a cool script but it looks like setting the “start” value to something other than 0 breaks external controls?

  • For everyone that’s looking to get the start position to set the starting position at random, look below.

    —–#1
    ** Basically, I created a variable. This of course will create a variable that uses math.random to find a number between * (which is 0), and carouselLi.length (which sets itself dynamically to the amount of list items you have under your ul.)

    var countlis = Math.floor(Math.random()*carouselLi.length);

    —–#2
    And edited:
    if (o.circular) {
    ul.prepend(tLi.slice(tl – v – 1 + 1).clone()).append(tLi.slice(0, v).clone());
    o.start += v
    }

    to:

    if (o.circular) {
    ul.prepend(tLi.slice(countlis).clone()).append(tLi.slice(0, v).clone());
    o.start += v
    }

  • Chris

    I’ve implemented this into a site we’re working on but it seems to break on the last three logos, no matter what those last three logos are. I’m hoping you can help out.

    http://likewise.edstage.com

    On the above site, there’s a logo rotator near the bottom that’s used for client testimonials. You can either let it run automatically or click forward manually, but it’ll stop working on the University of Oregon. Once it circles back it’ll start working again.

    It’s not just that the logos don’t receive the correct CSS styling, but even clicking them doesn’t work, as it should manually force that logo and description to become active.

    I’ve moved and removed the last three items but it’s the same, regardless of which three are last. It’s baffling.

    Can you shine some light?

    Thanks in advance.

  • FD

    When using start and circular the carousel goes wrong.

    This line:
    if(to<=o.start+v-1) { // If first, then goto last

    Must be:
    if(to<=v-1) { // If first, then goto last

  • J

    Have included jquery.easing.1.3.js to added ‘easeInOutCubic’ to the animation. This works great on my iMac in all browsers, very smooth! BUT on pc the animate is very jerky on all browsers. Can you let me know whats up with this?

  • Thanks for this great script bro. but I wonder if there’s a possibility to add page by page navigation.. I mean if for example there’s a total of 15 items.. but only 3 is shown.. then there’s 5 pages, each with 3 items.. so is there’s a way to show page navigation ?

    something similar is in this website
    http://www.bbc.co.uk/arabic/worldnews/2010/11/101129_wikileaks_issues.shtml

    just navigate to the bottom of that page… I liked this one very much.. sadly it’s private scripting and I tried even to have a clue how it’s working to see if I can make something similar from ground.. but it was very complicated…

  • azeijoe

    Hi,

    Just a little issue on when you use jcarousel on images with text on the bottom enclosed with or or something, it won’t show text as it goes longer…

  • Really trustworthy blog.. Its also informative information. Thanks for the post and assimilation in adequate others.

  • kjhenrie

    Thanks for contributing a great carousel plugin.

    I uncovered an issue in which if I set “circular” to false and a “start” value > total images – “visible” the previous button will not work. I fixed it by changing line 300 from:

    if(toitemLength-v) return;

    to:

    if(toitemLength-v && curr<to)) return;

  • Hi, I’m using the carousel to slide elements with variable heights, the content gets clipped… Here’s a hack to fix this with custom callbacks, don’t know if any neater solution:

    beforeStart: function(a) {
    $(‘.your_elements_class’).height(200); // reset to default height
    },
    afterEnd: function(a) {
    height = a[0].scrollHeight;
    a.height(height);
    }

  • domichal

    When start position is set and different than 0, carousel acts weird – scrolls forward ok, but if you try going backwards it cuts out some elements – their number rely on the start element number – I guess that’s a bug.

  • domichal

    sorry, there’s no way to edit post – it may be obvious, but I forgot to say it happens with carousel where circular set to be true.

  • Sam

    Hi, im testing this jcarousellite on a text based unordered list that varies in height from li to li and the accuracy of the circularity drops drastically with huge gaps in between.

    Was this plugin meant for fix width/height? i should mention that im building a vertical carousel.

    Thanks

  • “jCarousel Lite – A jQuery plugin” is one of my favorite post. I bookmark this useful post for future. Hope the popularity of this post will increase day by day. Keep it update.

  • sam

    if “circular: false” is set

    and the li items is odd and the scroll is even the last image will never be shown

    To fix use the following code….

    } else { // If non-circular and to points to first or last, we just return.
    if(to>itemLength-v) {
    curr = itemLength-v; //v=in view — go to v – number of items
    }
    else if(to<0) {
    curr =0;
    }
    else curr = to;
    } // If neither overrides it, the curr will still be "to" and we can proceed.

  • Trevor

    Great work. I have a couple of mods I would like to contribute pending approval from the company I am working with.

    Thanks Again!

  • Goodluck

    Great work! I love it and it works on my site, but only one thing I can’t figure out is: how to get rid of the bullet from the list of the image? Thanks!

  • Iñaki

    Thanks for this great plugin!!

    Is there a way to do a pageup/pagedown scroll? I know I can do it setting the scroll variable to the same value as visible, but I want to have both next/prev controls and pageup/pagedown controls… is that possible?

    Thanks!

  • Usually I do not write-up on blogs, but I need to say that this write-up incredibly
    forced me to try and do so! Thanks, extremely nice article.

  • Dmitry

    hi. i like your jcarousellite plugin.
    but i need to have width of my carousels fixed and set by css, displaying as many images as possible for this carousel width.

    so i add option fixedWidth.
    line 220 of jcarouselelite_1.0.1.js : fixedWidth:false,
    and i wrapped
    div.css(sizeCss, divSize+”px”);// Width of the DIV. length of visible images

    with condition:
    line 253 of jcarousellite_1.0.1.js:
    if(!o.fixedWidth)
    div.css(sizeCss, divSize+”px”);// Width of the DIV. length of visible images

    so now it works fine for me. you can add the same functionality in next versions, if you wish. i think it’ll be rather handy.

  • Vaishali

    Hey, I am using this one to scroll through a set of 10 images. I have set visible: 2 meaning show 2 images at a time, and circular: false. What I now want is a vertical scrollbar in addition to mouse scroller. Is it possible? Overflow attribute is not working in the class declaration.

  • As a Newbie, I am continuously searching online for articles that can be of assistance to me. I manage a Google Pagerank 5 Free Link Web directory “shotlisbon2008 dot com” I’d like you submit your site to my directory for free as it would enhance your site ranking in search engine and you would get more traffic.

  • aya

    I love this plugin, but i found a problem i think more people have seen it. Is there allready a solution ir could someone take a look at this?

    When you make a vertical scrolllist, with lets say 8 items, visible=4 and scroll = 3, it scrolls correctly 2 times, so items 1-4, 4-7 but when you do another scroll you would expect 7-8-1-2 but it flips to 1 and than scrolls one more. and than you see 2-5

  • chemm

    hi
    could you provide solution for the following bug
    when carousel is set to circular and
    have start different from zero
    when using teh the prev btn, the carousel is not scrolling through out all the slides but limited ones.

  • I’ve got this working on my photo blog and it works great except that there is a big gap when vertical images are in the slideshow. As per the docs I’ve added width and height to each image (even the li surrounding the image) yet it still does this.

    here’s my current code and the gaps can be seen at my blog

    $(function() {
    $(".thumbs").jCarouselLite({
    auto: 2500,
    visible: 6,
    circular: "true",
    btnNext: ".next",
    btnPrev: ".prev"
    });
    });

    thank you for your help and time.
    </code]

  • I’ve been exploring and searching for a little bit for any high quality articles or blog posts on this sort of area . Exploring in MSN Search I at last stumbled upon this site. Wow, great, finally. Upon Reading this information So i am happy to convey and realize that I have an incredibly good uncanny feeling I discovered exactly what I needed a lot. Thanks a lot. I most certainly will make certain to of course do not forget this website and give it a glance on a constant basis to compare it with my industrial uninterruptible power supply websiteUnquestionably believe that which you stated. Your favorite justification appeared to be on the net the easiest thing to be very well aware of. I say to you honestly, I definitely get irked while people consider worries that they plainly don’t know about. Well,You managed to hit the nail upon the top of the hill and defined out the whole thing without having side-effects , people can take a signal. Once again I say directly to you I Will probably be back to get more. Good Day

  • Youssef Ali

    I want to use the JCarousel plugin with and elements not and .
    Can i do this?

  • Youssef Ali

    Hi, please help me;
    I want to use the JCarousel plugin with “table” and “td” elements not “ul”and “li” .
    Can i do this?

  • Jeremy

    Hi,

    Great plugin. I am using the auto facility. I am showing the carousel in a tooltip feature that i have buiilt. When the tooltip is closed/hidden I would like to stop the carousel. Is there a way to do this?

    Many thanks
    Jeremy

  • I am trying to make this display images randomly but am unsure how to add the math.random code. are you able to help? Thank You!

  • Diane

    Hello
    I am not having any success in installing your carousel! I have stripped the whole page back to just the carousel required items, but all I am getting is the three images sitting vertically as a list on a blank page. I have downloaded jquery-1.4.4.min.js and jcarousellite_1.0.1.min.js, and there is no other code on the page.

    My code seems correct, as I copied it onto a forum and someone there copied it off and it all worked fine!

    Have you any thoughts on what could be stopping the code from working on my machine? I am using Firefox and Safari – no luck with either.

    Hope you can help!

  • Prasad

    Hi Ganeshji,
    I have problem,when I reconstruct a carousel with a new data it does not reset the carousel state. ie if earlier i had 5 items and after reconstruction i have 3 items,still i can click 5 times on btnNext

  • Senthil

    Hi,

    I have implemented one Horizontal(Medium) and a vertical(thumb) carousel listings. Horizontal carousel visible one image and vertical carousel visible 6 images. I need to show the corresponding medium image when clicked a thumb image in the carousel listing. I had used the jcarousel lite. Can you please help me how can i control the listings each other.

    Hope you can help!

  • Hi! when I set up “start” attribute for example “1” and after initializing click “prev btn” – slider become crazy!

  • Great plugin. Can’t believe how small it is, and a lot more versatile than you give yourself credit for – I bet most people who use jcarousel coudl easily get away with using yours.

    I’ve made a minor addition which I thought I’d tell you about as it’s only a few extra lines of code and probably useful to quite a few people – enabling an auto-scrolling carousel to stop once a user clicks on any of the nav buttons

    1. store the autoscroll interval in a variable
    if(o.auto)
    var auto = setInterval(function () {

    2. Add the following helper function

    function stopOnClick() {
    if (o.stopOnClick) {
    clearInterval(auto);
    stopOnClick = function () { return };
    };
    }
    3. Call the helper within each of the click handlers

    Also, another suggestion is

    if(o.afterEnd)
    o.afterEnd.call(this, vis(), curr-1);

    – I’m using this so that I can update classes on my numerical navigation links, but there’s all sorts of things this could be used for

    Cheers

  • Jernej Lekše

    Hi.

    I will use this plugin for text lists. Because it is not always the first item tallest, i had to go over all list.
    Might this part of script will help anyone, so i post it here.

    Add this before li.css({width: …):
    var maxHeight=0;
    $(“li”, ul).each(function() {
    if(maxHeight < $(this).height()) {
    maxHeight = $(this).height();
    }
    });

    Replace:
    li.css({width: li.width(), height: li.height()});
    with
    li.css({width: li.width(), height: maxHeight});

    Regards,
    Jernej Lekše

  • errol187

    hi

    am looking for a quick way to stop the animation on hover. This would be a brilliant addition but I am finding it difficult.

    errol187

  • Gabriela

    Actually, me too, I need it to stop once user passes the mouse over.

  • hey,
    I’m having the damnest time trying to utilize this awesome plugin. I really haven’t been able to find anything else that will allow me to do what I need to do for this client. However, I’m having trouble even getting it working. I’m using it in conjunction with lightbox 2. Not only am i slightly confused on how to set up the divs, it just seems like its not working at all.
    I’m trying to use it on this site here http://patricelena.com/indentity.php. please help, the deadline is approaching fast (feb 7), and i’ve tried to do this for like w days to no avail.
    any help would be awesome.
    thanks

  • nevermind. It seems as though the ‘prototype.js’ script was interfering with the jcarousel script for some reason. I guess all i have to do now is find a light box script that works with this plugin.

  • Sufyan

    Hi Ganesh. I would like to know is there any license to use jcarouselLite plugin? is it free to use?

  • mary

    There’s a problem regarding the “start” parameter. When the start parameter is equal to “0” and the previous and next is clicked,the carousel slides or moves to the correct or content but when the parameter is not equal to zero, the carousel jumps to incorrect page.
    For example, my start parameter is equal to 5, and when the previous or next button is clicked it jumps to index 8 or to number 8.That’s not supposed the behavior of the carousel right?The carousel should move to index 6 for next or index 4 for previous.Thank you so much!

  • Ron

    I’m actually hoping you’ll add a way to destroy the carousel. One of the problems I’m having with jcarousel is that if I remove the markup that contains the carousel (through dynamic loading of new content through ajax), the script will attempt to pull the carousel dimensions even though it’s no longer in the DOM. I suspect it’s the same issue as hiding the carousel before it’s ready.

  • Fabulous to see a properly lightweight but very capable carousel, thank you.

    …now the ask 😉 It would be great to have a jQuery 1.4 version.

  • lan

    I too am interested in displaying captions along with the carousel. Specifically, it would be really nice if the post title was able to be displayed (in the case of wordpress usage) below the image or on it. Is this possible now?

  • Tony

    Any chance there might be a way to pause an auto scrolling carousel with a mouse-over event? I’m looking to implement this as a vertical news scroller and it would be nice if it stopped scrolling when a link is hovered.

    Thanks!

  • Thanks for your work. I’ve made a few changes to your script as well as fixed a bug (mentioned by #1014).

    // Changes:
    //
    // Added preventDefault() to btnPrev/Next to keep them from firing when clicked when “disabled” (If they were , this would result in the href firing.
    // Moved button state code into function and called on init as well as on scroll (Previous button would be enabled on load even though you are at the beginning of the list).
    // Fixed bug where you couldn’t get to last items if the options.scroll was 0 && 0 ? go(curr – o.scroll) : go(curr + o.scroll);
    });

    if (o.auto)
    setInterval(function () {
    go(curr + o.scroll);
    }, o.auto + o.speed);

    function vis() {
    return li.slice(curr).slice(0, v);
    };

    function btnstates() {
    $(o.btnPrev + “,” + o.btnNext).removeClass(“disabled”);
    $((curr == 0 && o.btnPrev)
    ||
    (curr >= itemLength – v && o.btnNext)
    ||
    []
    ).addClass(“disabled”);
    }

    function go(to) {
    if (!running) {

    if (o.beforeStart)
    o.beforeStart.call(this, vis());

    if (o.circular) { // If circular we are in first or last, then goto the other end
    if (to 1, then the “to” might not be equal to the condition; it can be lesser depending on the number of elements.
    curr = to == o.start – v – 1 ? itemLength – (v * 2) – 1 : itemLength – (v * 2) – o.scroll;
    } else if (to >= itemLength – v + 1) { // If last, then goto first
    ul.css(animCss, -((v) * liSize) + “px”);
    // If “scroll” > 1, then the “to” might not be equal to the condition; it can be greater depending on the number of elements.
    curr = to == itemLength – v + 1 ? v + 1 : v + o.scroll;
    } else curr = to;
    } else { // If non-circular and to points to first or last, we just return.
    if (to < 0)
    if (curr – v itemLength – v)
    if (curr + v < itemLength)
    curr = itemLength – v;
    else
    return;
    else curr = to;
    } // If neither overrides it, the curr will still be "to" and we can proceed.

    running = true;

    ul.animate(
    animCss == "left" ? { left: -(curr * liSize)} : { top: -(curr * liSize) }, o.speed, o.easing,
    function () {
    if (o.afterEnd)
    o.afterEnd.call(this, vis());
    running = false;
    }
    );
    // Disable buttons when the carousel reaches the last/first, and enable when not
    if (!o.circular) {
    btnstates();
    }

    }
    return false;
    };
    });
    };

    function css(el, prop) {
    return parseInt($.css(el[0], prop)) || 0;
    };
    function width(el) {
    return el[0].offsetWidth + css(el, 'marginLeft') + css(el, 'marginRight');
    };
    function height(el) {
    return el[0].offsetHeight + css(el, 'marginTop') + css(el, 'marginBottom');
    };

    })(jQuery);

  • Yup… it sucked….

    Let’s try that again:

    (function ($) { // Compliant with jquery.noConflict()
    $.fn.jCarouselLite = function (o) {
    o = $.extend({
    btnPrev: null,
    btnNext: null,
    btnGo: null,
    mouseWheel: false,
    auto: null,

    speed: 200,
    easing: null,

    vertical: false,
    circular: true,
    visible: 3,
    start: 0,
    scroll: 1,

    beforeStart: null,
    afterEnd: null
    }, o || {});

    return this.each(function () { // Returns the element collection. Chainable.

    var running = false, animCss = o.vertical ? “top” : “left”, sizeCss = o.vertical ? “height” : “width”;
    var div = $(this), ul = $(“ul”, div), tLi = $(“li”, ul), tl = tLi.size(), v = o.visible;

    if (o.circular) {
    ul.prepend(tLi.slice(tl – v – 1 + 1).clone())
    .append(tLi.slice(0, v).clone());
    o.start += v;
    }

    var li = $(“li”, ul), itemLength = li.size(), curr = o.start;
    div.css(“visibility”, “visible”);

    li.css({ overflow: “hidden”, float: o.vertical ? “none” : “left” });
    ul.css({ margin: “0”, padding: “0”, position: “relative”, “list-style-type”: “none”, “z-index”: “1” });
    div.css({ overflow: “hidden”, position: “relative”, “z-index”: “2”, left: “0px” });

    var liSize = o.vertical ? height(li) : width(li); // Full li size(incl margin)-Used for animation
    var ulSize = liSize * itemLength; // size of full ul(total length, not just for the visible items)
    var divSize = liSize * v; // size of entire div(total length for just the visible items)

    li.css({ width: li.width(), height: li.height() });
    ul.css(sizeCss, ulSize + “px”).css(animCss, -(curr * liSize));

    div.css(sizeCss, divSize + “px”); // Width of the DIV. length of visible images

    btnstates();

    if (o.btnPrev)
    $(o.btnPrev).click(function (ev) {
    ev.preventDefault();
    return go(curr – o.scroll);
    });

    if (o.btnNext)
    $(o.btnNext).click(function (ev) {
    ev.preventDefault();
    return go(curr + o.scroll);
    });

    if (o.btnGo)
    $.each(o.btnGo, function (i, val) {
    $(val).click(function () {
    return go(o.circular ? o.visible + i : i);
    });
    });

    if (o.mouseWheel && div.mousewheel)
    div.mousewheel(function (e, d) {
    return d > 0 ? go(curr – o.scroll) : go(curr + o.scroll);
    });

    if (o.auto)
    setInterval(function () {
    go(curr + o.scroll);
    }, o.auto + o.speed);

    function vis() {
    return li.slice(curr).slice(0, v);
    };

    function btnstates() {
    $(o.btnPrev + “,” + o.btnNext).removeClass(“disabled”);
    $((curr == 0 && o.btnPrev)
    ||
    (curr >= itemLength – v && o.btnNext)
    ||
    []
    ).addClass(“disabled”);
    }

    function go(to) {
    if (!running) {

    if (o.beforeStart)
    o.beforeStart.call(this, vis());

    if (o.circular) { // If circular we are in first or last, then goto the other end
    if (to 1, then the “to” might not be equal to the condition; it can be lesser depending on the number of elements.
    curr = to == o.start – v – 1 ? itemLength – (v * 2) – 1 : itemLength – (v * 2) – o.scroll;
    } else if (to >= itemLength – v + 1) { // If last, then goto first
    ul.css(animCss, -((v) * liSize) + “px”);
    // If “scroll” > 1, then the “to” might not be equal to the condition; it can be greater depending on the number of elements.
    curr = to == itemLength – v + 1 ? v + 1 : v + o.scroll;
    } else curr = to;
    } else { // If non-circular and to points to first or last, we just return.
    if (to < 0)
    if (curr – v itemLength – v)
    if (curr + v < itemLength)
    curr = itemLength – v;
    else
    return;
    else curr = to;
    } // If neither overrides it, the curr will still be "to" and we can proceed.

    running = true;

    ul.animate(
    animCss == "left" ? { left: -(curr * liSize)} : { top: -(curr * liSize) }, o.speed, o.easing,
    function () {
    if (o.afterEnd)
    o.afterEnd.call(this, vis());
    running = false;
    }
    );
    // Disable buttons when the carousel reaches the last/first, and enable when not
    if (!o.circular) {
    btnstates();
    }

    }
    return false;
    };
    });
    };

    function css(el, prop) {
    return parseInt($.css(el[0], prop)) || 0;
    };
    function width(el) {
    return el[0].offsetWidth + css(el, 'marginLeft') + css(el, 'marginRight');
    };
    function height(el) {
    return el[0].offsetHeight + css(el, 'marginTop') + css(el, 'marginBottom');
    };

    })(jQuery);

  • Hello All

    I have used this plugin for auto scrolling banners vertically – But I have a problem that, when the page first loads these banners are at the right about 20px from actual position and after 2-3 secs it will move to the correct position.

    Here you can see my web page – http://stage.ednaccess.com

    I am looking for your reply folks. Hope I can solve this issue from your replies.

    – Chandu