jQuery Carousel

Posted Wednesday 18th August, 2010

Update November 2010: Documentation for this jQuery Carousel can now be found here: Modern Carousel - Tim Huegdon’s Projects

Recently I’ve had the need to build several jQuery widgets, because, no matter how many already exist in the wild, they never seem to have all the features I require. Reinventing the wheel? Well yes, but there’s no harm if the current wheel doesn’t fit the vehicle.

Further to that, building widgets with various JavaScript libraries is actually pretty good fun, and is definitely a good way of familiarising yourself with that particular library. Having recently moved from using YUI to the more widely used jQuery, these widgets have aided my education.

So without further ado, here’s the first: the carousel.


Take a look at the page of example carousels first, to see the various implementation options.

Source Code

You can find all the source code hosted on GitHub here, with tarballs and zips:

Modern Carousel — GitHub repository



The core HTML of the carousel should look something like this:

<div class="carousel">
    <div class="clip">
        <ul class="horizontal">

The carousel, clip, and horizontal classes are all used by both the core CSS and the JavaScript to build the carousel. As a result, they are required features.

The carousel div must be the direct parent of the clip div, which in turn must be the direct parent of the ul element. The current version of the carousel script does not support the use of an ol, but it’s one of the features on my todo list.

For a vertical carousel, you should substitute the horizontal class with vertical.


The only required CSS for the carousel, is the carousel.core.css file:

<link rel="stylesheet" href="css/carousel.core.css" type="text/css" charset="utf-8">

My examples also include a CSS skin file that applies some styling to the carousel controls. Feel free to reuse this, or poke at it to come up with your own styles:

<link rel="stylesheet" href="css/carousel.skin.css" type="text/css" charset="utf-8">


To add the JavaScript, you simply need to include the script—along with jQuery—somewhere on your page. It’s best to include scripts at the bottom of your pages, before the closing body tag, as some browsers can delay loading of the rest of the page whilst the script loads.

<script type="text/javascript" src="js/jquery-1.4.2.min.js" charset="utf-8"></script>
<script type="text/javascript" src="js/jquery.carousel.2.0.js" charset="utf-8"></script>

Once you’ve done that, you can simply apply the carousel() method to any jQuery object, like so, to get the default options:

<script type="text/javascript">

Alternatively, you can configure the carousel by passing it a configuration object like so:

<script type="text/javascript">
        "loop": true,
        "autoplay": true,
        "hovercontrols": true,
        "hoverpause": true

Parameters for the configuration object are as follows:

Option Value
visiblePanes The number of panes that are visible in the clipping area.
panesToMove The number of panes to move the carousel when next/previous are clicked.
pagination Boolean value to turn on or off pagination.
speed Speed of the transition between panes.
loop Boolean value to specify if the carousel loops after the final pane has been reached.
autoplay Boolean value to specify whether the carousel autoplays.
hovercontrols Boolean value to specify if the controls only display when hovering over the carousel.
hoverpause Boolean value that activates pause when hovering the mouse over the carousel.
delay The delay, in milliseconds, between transitions when the carousel is playing.
transition A reference to a transition function defined at $.fn.carousel. E.g. “yourTransitionHere” would reference a function defined at $.fn.carousel.yourTransitionHere.

For more on the transition hooks, it’s probably best to take a look at the code. When I have more time, I’ll look at updating the GitHub wiki with details myself.

Included in: Development, JavaScript, Tools, UI, Web, Web Standards, Widgets, jQuery


  1. Accessibility
  2. Agile
  3. Ajax
  4. Apache
  5. API
  6. Architecture
  7. Books
  8. Browsers
  9. CMS
  10. CouchDB
  11. CSS
  12. Design
  13. Development
  14. Django
  15. Email
  16. Events
  17. Gaming
  18. Grammar
  19. Hardware
  20. HTML
  21. HTTP
  22. Humour
  23. Idea
  24. Information Architecture
  25. JavaScript
  26. jQuery
  27. Lean
  28. Life
  29. Linux
  30. Literature
  31. Mac OS X
  32. Management
  33. Meme
  34. Microformats
  35. Monday
  36. MySQL
  37. Networking
  38. News
  39. Personal
  40. Photoshop
  41. PHP
  42. Process
  43. Python
  44. Reference
  45. REST
  46. Science
  47. SEO
  48. Server
  49. Site
  50. Sitepimp
  51. Social
  52. Spelling
  53. Syndication
  54. Testing
  55. The Future
  56. Thoughts
  57. Tools
  58. Tutorial
  59. Tutorials
  60. Typography
  61. UI
  62. UNIX
  63. Virtualisation
  64. Web
  65. Web Standards
  66. Widgets
  67. Wii
  68. Writing
  69. Xbox
  70. XHTML