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

  • Brad

    I am very happy with your work thus far, but I am having a bigger issue then I thought. Well, not so big, but noticeable in my eyes. I have a vertical picture carousel, then a second horizontal text carousel. These together act as my News Slider together. I have them timed exactly the same, but it seems that sometimes one or the other will slip off the timer and randomly skip an image or a text section and basically destroys the synch of the text and picture together. I either need some way of putting them together into one section so even if the timing is off it will still pair together, or I need to figure out why the timing is off. Thank you.

  • Ganeshji Marwaha

    @Brad #501: Brad, I get ur issue. If I can see it visually somewhere, I could help even better. Can you kindly direct me to some test page where this happens. Technically speaking, the timing should sync.

  • mboyden

    Great toolset overall, and definitely light. Thanks! One thing that would be nice for the auto-scroll would be to provide an auto-scroll direction, so that if you’d like to scroll automatically from left to right instead of right to left, or top to bettom instead of bottom to top. If this exists already, then I somehow missed it in all the good documentation and comments.

    Now, to figure out how to trigger the next, previous, and go events via javascript….

  • Bob

    I wanted to thank you for this plugin. It is a life saver.

    I do have one question though, how do I use the afterEnd “object” that is returned? I want to automatically show the larger image of the first visible thumbnail.

    I cannot seem to figure out how to use the object you are returning to achieve this.

    Thanks again!

  • Ganeshji Marwaha

    @mboyden #503: You didn’t miss it. Yes, there is no way to scroll in the opposite direction for auto-scroll. I am wondering how I missed such a useful feature. I will try and get around to doing it as soon as I am able to squeeze out some time. In the meantime, I suggest that it should be a small modification to the source and the source as you can see is pretty simple and well documented. Let me know if you succeed in getting this feature done. Thanks. In the meantime I will also try my best to get around to including this feature.

    @Bob #504: The object that is returned is a jquery object that is a collection of all visible elements. Using this object, you can get the first visible element (if you have more than one visible element). You should have some metadata associated to the element within the carousel (like in the “title” attribute of the “img” that is displayed. Using that metadata you can populate a larger image. Check out the “Custom Widget” in the jCarouselLite project page – http://www.gmarwaha.com/jquery/jcarousellite/index.php . This is not exactly the same as your requirement, but comes close. Hope that helps.

  • Bob

    I understand that. I have tried $(a+’:first’), etc and everything else I can think of but for some reason I get “undefined”.

    I am just setting the dynsrc attr and I use that. I just need to figure out how to use afterEnd to get the dynsrc of the first one.

    Thanks for helping.

  • Ganeshji Marwaha

    @Bob #506: I tried it out here. It is pretty straightforward to find the first carousel element. In my case carousel elements are “img” tags. So, here is what i did in the afterEnd method.

    afterEnd: function(a) { 
         console.log(a.find(":first").attr("dynsrc"));
    }
    

    That returned the “dynsrc” attribute for the first visible element of the carousel after the animation was complete.

  • Bob

    Sorry, thanks for the help.

    That does work…I just have never seen it like that. I.e. I was trying $(a).

    Thanks!

  • Bob

    Sorry to bother you again. I noticed the “fraction” that you can show and was messing around with it. Here is my code:

    $(“.widget .jCarouselLite”).jCarouselLite({
    btnNext: “.widget .next”,
    btnPrev: “.widget .prev”,
    visible: 3.3,
    circular: true,
    speed: 100,
    start: 1,
    beforeStart: function(a) {
    $(“.widget .mid img”).hide().attr(“src”, ‘/images/icons/spacer.png’);
    },
    afterEnd: function(a) {
    $(“.widget .mid img”).attr(“src”, a.find(“:first”).attr(“dynsrc”)).fadeIn(‘slow’);
    }

    Everything works except that instead of showing 3 full and one partial, I get 2 full and 2 partial. Ideally it would be 3 full to the left, and the partial on the right, but it is showing a partial #1, 2 full, and then a partial #4.

    Any thoughts? (in your example you have circular set to false, but I want it set to true – setting to false “fixes” the problem).

    Thanks.

  • Hello !
    I have tried to add your carroussel on my website ut I’ve got a problem. It’s totally ok on Firefox but not in IE (all versions).
    Do you know if there are some issues?
    I’ve got 2 carrousels on my page. The js is external and contain these lines :

    $(function() {
    $(“.catalog-horizontal”).jCarouselLite({
    btnNext: “.nextproj”,
    btnPrev: “.prevproj”,
    });
    });

    $(function() {
    $(“.catalog-vertical”).jCarouselLite({
    btnNext: “.next”,
    btnPrev: “.prev”,
    vertical: true,
    visible: 2

    });
    });

    I’ve got one vertical carousel and one horizontal on the same page.
    Here is an exemple of the html code for the vertical carrousel :

    content1
    content2


    Is there a mistake in my code? Or the carrousel don’t work with IE (I’m quasi sure my code is wrong?!)

    Thanks for your help man and congrats for your work on this project.

    Kind regards

  • Sorry, the html code don’t work on the com…

    here it is :

    [div class=”container2″]
    [div class=”catalog-vertical”]
    [ul]
    [li]content1[/li]
    [li]content2[/li]
    [li]…[/li]
    [/ul]
    [/div][!–/catalog2–]
    [img src=”…” class=”prev” alt=”” /]
    [img src=”…” class=”next” alt=”” /]
    [/div][!–/container2–]

  • Brad

    My website is http://www.teamthinktank.net , you can see the issue there by refreshing. You might have to watch it for a bit to see the error. Also, I am a bit new to editing css/jquery files so I am not sure how to add in the fix for loading off screen. Maybe you can offer some help on how to isolate the loading of this dang twitter news deal. Any help will be appreciated!

  • Thanks for the excellent plugin! Is there an option to stop the auto scroll when the user hovers over an element in the carousel?

    – Jonah

  • Forgot to mention I am using jQuery 1.3.2

  • Mike

    Hi, I am playing around with your script and am having a bit of trouble.

    It doesn’t seem to handle uneven numbers of images properly when working with higher scroll values.

    Example, I have 12 images, 5 shown at a time & I want to scroll 5 images at a time… This is not smooth, it jumps around and doesn’t end up displaying the final 2 images at all unless I scroll backwards from the beginning… Different numbers of images combined with different numbers of pictures to scroll per click yield different results.

    Bottom line, when the # of pictures is not a multiple of the number of pictures being displayed & being scrolled, the plugin seems to fail.

    Any help you could offer on this would be appreciated. There is no documentation regarding this effect on your site.

  • Mike

    Hello again, browsing through your comments I found a user who had a similar problem… Your reply to him was the following

    “@Chad #410: I guess, the plugin looks for a minimum of “visible” elements to function properly. But anyways, what would you want displayed in the other 3 slots if visible:4 is given and you provide only 1 image in the “li””

    He did not reply. Some options for what would be displayed :
    1. The first 3 images looped around,
    2. 3 “items” of blank space.

    However, the least acceptable option for your script is probably “not displaying the extra image at all / breaking the script”

    It would be much appreciated if you could help me figure out a solution to this problem.

  • Tier

    Hi,
    I got the same sync-problems as Brad does (#512).
    See this demo page using two synced carousels:
    http://themeforest.net/item/wordfolio/full_screen_preview/38723
    Just click several times on the up-arrow and the two carousels will be out of sync.
    I tried a lot with changing all variables, but it does not get better.

  • Mikhail Novikov

    Hello!

    First of all thanks a lot for this awesome plugin.

    I’ve used it on one of my projects a lot but now I need to make it loadable through AJAX, because loading all carousel items normally results in huge number of requests. I wonder is there a way to reinitialize jCarousel lite so it will take new items into account.

    Thanks, Mikhail

  • Ganeshji Marwaha

    @Bob #508: No problem. Glad you got it working. Thanks for using jCarouselLite.

    @Bob #509: Yes, i see your issue. I will debug and fix it as soon as possible and post an update. Sorry for the inconvenience.

    @detruck #510, #511: I tested it locally it works fine for me in all browsers. I guess, there should be something wrong in your HTML code. If you could direct me to a test page where I can see the issue, I will be able to help you. The HTML u posted is incomplete and I understand that HTML gets rendered in my comment box making it difficult to post HTML. So, I suggest just host a test page somewhere and send me the link. I will take a look at it.

    @Jonah West #513: Sorry, but there is no option for that right now, although I am thinking of adding one in the future.

    @Mike #515, #516: After looking at your comment, I went ahead and tested what you said locally and it seems to work very fine buddy. If you have say 11 images in the carousel and have like 5 elements visible at anytime and your scroll value is 5 again. Then, initially 5 images are getting displayed. On click of the next button, the next 5 images are getting displayed. On click of the next button again, the 11th image and the first 4 images are getting displayed and I find this to be the correct behavior. If you are getting any other behavior please make a test page and direct me to it. I will be glad to help.

    @Brad #512: I see what you are talking about. Sync issue right. Lemme see what the bug could be. Thanks for pointing out.

    @Mikhail Novikov #518: Sorry, but jCarouselLite doesn’t support loading using ajax, coz that essentially will add quite a bit of code to the core and will make it jCarouselHeavy. But, you dont have to lose heart as there are quite a few other carousels built using jQuery that are not as light, but support ajax. Thanks for trying jCarouselLite.

    @Tier #517: I see your issue. I will try and debug it as soon as possible. Thanks for pointing out the issue.

  • Luis Arias

    Hi,

    I just put together a carousel using your plugin version 1.0.1 that is visible here:

    http://pw.pilango.com/

    It works fine in firefox 3.5 on ubuntu, but we are having issues on firefox 3.5 windows and also on chrome. Do you see anything wrong on your end ? I am setting the li elements width to auto and the carousel’s width to 853 px after initializing the component in order to get the type of display that we are looking for.

    Thanks for your help !

  • Lauren Russell

    @Ganeshji and @Mike #515
    I found the same bug Mike describe when circular is false. If I have 19 elements, and I have scroll set to 3, visible set to 3, and circular set to false the 19th element is not shown.

  • Thanks for looking into it. I am thinking maybe the reset function is a bit messed up or something. Since the two carousels are of different size and so forth, I think the pictures tend to reset faster because it has a set timer? I could be totally wrong, but I have been aggrevated by this issue for a while now. Let me know what you can come up with as a reasonable fix. Thanks!

  • Luis Arias

    Ok sorry for the false alarm in #520, working fine under IE and Firefox now. Seems using $(function …) instead of $(document).ready(function …) did the trick although I thought these where equivalent. I’ll continue doing some more cross platform / cross browser tests just in case ! 🙂

  • Wichert Akkerman

    I made a small change to this plugin which may be useful for others: instead of hardcoding the use of ul and li for the list and its items I have made them configurable. I use this for markup which uses a for the list and a series of elements for the contents.

    I’ve put the diff at http://www.wiggy.net/files/flexiblelists.diff

  • kazes

    Hello,

    thanks fo the plugin.
    I’m trying to use the External Control but there is one issue when you set “start” method.

    For example I have 4 item I want to navigate through and my code is :

    jQuery(“.externalControl .jCarouselLite”).jCarouselLite({
    visible: 1,
    start: 2,
    btnNext: “.externalControl .next”,
    btnPrev: “.externalControl .prev”,
    btnGo: [“.externalControl .bt1”, “.externalControl .bt2”, “.externalControl .bt3”, “.externalControl .bt4”]

    });

    If start is not 0, here 2, then it won’t loop correctly if you use the “prev” button.

    Any idea please? 🙂

  • Michael

    Hi,

    Just wondering, is there a way to Auto-Pause scrolling when in “auto” mode?

    Cheers,
    Michael.

  • Michael

    Ooops, sorry, forgot to mention during onhover… 🙂

  • Hi, congratulations for the work! Please when I upload my site in IE7 the images are superimposed, what may be occurring? In Firefox and IE6&8 are perfect. Sorry, but i´m not fluent in english..

    http://www.testadoporelas.com.br

    Thanks!

  • Hi Ganesh! Thank you for an awesome plugin! It works like a charm until I do add “circular: false,” (without the “s) to my carousel. For some reason it just won’t scroll the elements. It still hides them properly and everything, it just won’t scroll. I tried adding an auto-option as well, but that didn’t work either.

    Any help would be madly appreciated!

  • Ganeshji Marwaha

    @Luis Arias #520: Try setting the width property of the individual “li” elements and the content within the “li” in your css.

    @Lauren Russell #521: Yes, I see the issue. It works fine with circular: true though. But lets assume that it works in non-circular mode. What would be the result. You may have an empty element padded to the end to show a blank “li” right. Then, even if you have it in circular mode, there wont be a smooth feel for the carousel because you will be seeing one or more padded elements in the carousel. In any case, I will look into this issue. Thanks for pointing out.

  • Ganeshji Marwaha

    @Luis Arias #523: Glad you got it working

    @Wichert Akkerman #524: Good job. Simple yet powerful change to allow any HTML elements inside the carousel. I had it specific to ul and li because they look to be semantically right for a carousel.

    @kazes #525: Please post some test page and direct me to it. I will take a look.

  • Ganeshji Marwaha

    @Michael #526: Sorry, but none available so far with the plugin itself. But, i remember that another fellow jcarousellite user had modified the code to accept this feature as well. Check out the comments section slowly. You should be able to find one for sure.

    @Marilise #528: It seems to be working. Just that the height seems too high. This is just some CSS issue. Check the margin size, and also check for some double margin issue with IE.

    @Niclas #529: Can you please host a test page and direct me to it. I will take a look.

  • Tier

    Hi Ganeshji,

    no news for #517?

  • Greetings!
    I find your plugin very cool and I used it on my company’s page and everything works fine, but…

    There is a small issue. As I view my page on opera (only) and try to refresh the page containing the carousel it breaks (the dimensions of containers inside change, some new containers appear etc.) Could you take a look at the issue?

    Thx in advance,
    Simon

  • Ganeshji Marwaha

    @Tier #533: Sorry. Trying to debug. The issue doesn’t occur always and is really getting hard to debug. Let me know if you find out anything

    @Simon #534: Make a test page and direct me to it. The carousel on this site works perfect with opera even after a refresh. So, we will have to check out your css only.

  • @Ganeshji: http://inteaao.com/carousel/ <- there you have it.

    Thanks!

  • Ginger

    Hi and thanks for great plugin!:D Is there any way to add caption bellow images?

    My html structure is the following:

    CAPTION

    but caption doesn’t show!!!

    If a disable Jcarousel then everything is ok! When I enable it then caption disappears!

    Any help please??:D:D

  • Simon

    Hi, I decided to put the site online and it’s -> fuero.pl

    Try navigating through it using the menu and refresh sites that have a carousel, the error should occur (ot did a minute ago)

    Thanks!

    Simon

  • Ginger

    Hi again! Ok I solved by myself the above!:P Yet, I have an other question… Is there any chance to add multiple rows to slide, instead of one? Thanks again!!!

  • Ganeshji Marwaha

    @Ginger #539: Glad that you got it working. And yes, use “scroll: 2” as its option for scrolling 2 elements. You can give any number to the scroll attribute

  • Ganeshji Marwaha

    @Niclas #536: I checked your test page. The problem is simple. Your carousel is set to display 3 images at once, but the css for your carousel allows it to show only one. Since you have circular:false and only a total of 3 elements and visible is set to 3 by default, there is no activity on the click of the next button. To test it, just change visible to 1 and then you should see activity in the carousel. But that is not the solution. Your carousel elements should have width set explicitly for the plugin to calculate the entire carousel’s width. Fix the css and then you should be able to see all 3 carousel elements at once. Hope that helped.

  • Ganeshji, thank you so much!

  • Nicholas

    Are you planning to implement an option to display captions for the images? It would be nice to have that feature

  • Paul

    Hi Ganeshji, I think I have a similar problem to others. Basically I am using circular: false and visible:6 – the problem is that towards the end of the images the scroller does not scroll left/right. If I reduce visible to say 5, then it works OK, but does not display correctly.

    For an example, have a look at http://mardbalkarts.com.au/staging/artists07.html – on anything after this image the same problem occurs, but anything before this page works just fine.

    I am confused!

  • sanjeev kumar

    Hi Ganeshji,

    How to make it scroll on mouseover on next and prev button?

    Thanks,
    sanjeev kumar

  • Charley

    Is there a way to add a play/pause button to the carousel when it’s in slideshow mode?

  • Excellent script, Ganeshji.

    @mboyden #503 — The answer turns out to be ridiculously simple! To make the scroller move in the opposite direction, just open up your copy of jcarousellite and look for this:

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

    and change “curr+o.scroll” to “curr-o.scroll”. That’s it!

    LVX
    TF

  • Ganeshji Marwaha

    @Niclas #542: Glad you got it working. Thanks for using jCarouselLite

    @Nicholas #543: Can you elaborate further. What exactly do you mean when you want jCarouselLite to display captions for images. If it is a feature many of us would like having, I can definitely implement it.

  • Ganeshji Marwaha

    @Paul #544: Found the issue and I am in the process of fixing it. It is almost done. I will update this blog entry once I upload the fixed version and will post a comment as well. Kindly revisit again in a couple of days to check out the revised version and see if it solves your problem

    @Sanjeev Kumar #545: At present, jCarouselLite takes in the expression for btnNext and btnPrev and binds it to a click event only. This is because, it is the most used use-case. If this feature is requested by many others we can implement it into the plugin itself. But for now, I would suggest to modify the source of the plugin to achieve the effect. Look for the place where the buttons are bound to the click event. Instead, bind it to hover(). Remember, click takes place only once per user click. Hover, event is fired repeatedly as long as the user hovers over the button. So, take care when implementing the feature.

  • Ganeshji Marwaha

    @Charley #546: Unfortunately no. But, I am working on an updated version of jCarouselLite which supports pauseOnHover. Will check if I can implement something along the lines of play/pause button when I complete that. Do check back for an Update in this blog entry to see if that feature is implemented. Thanks for using jCarouselLite

    @AsIf #547: Thanks for helping fellow jCarouselLite users around.