Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Carousel widget

This project is no longer activly maintained

This is a generic carousel widget which can be used with any content. Highly customizable and extendable. It works in any browser on any device.

Your pull requests are more than welcome and we're happy for any contribution.

travis status

Add an image gallery to your app

Below is a sample of how you create a simple image carousel. Add the script to the bottom of the page

<script src="carousel-1.0.0.min.js"></script>

Then add markup for listing the images.

    <div id="imageList">
        <img src="" alt="">
        <img src="" alt="">
    <div id="prevNextNavigation" class="nextprev">
        <a class="prev" title="Previous"><span class="hidden">Previous</span></a>
        <a class="next" title="Next"><span class="hidden">Next</span></a>

Now let's wire up the JS code required to make this thing work. This should be in a separate file loaded after the carousel lib.

    var sourceImageList = document.getElementById("imageList");
    var imageList = carousel.elementList.create(sourceImageList);
    var controller = carousel.controller.create(imageList);

    var imageProjector = carousel.animatedProjector.create(controller, imageList, {
        duration: 500,
        animator: carousel.horizontalSlider
    var imageCarousel = imageProjector.buildCarousel();
    carousel.setupTouchNavigation(controller, imageCarousel); = "none";


That's it! You can use this same setup for things other than images, you can loop through any type of DOM node. Wether it's an image, canvas, svg or whatever.

The carousel consists of many components which can easily be composed together to give the carousel different behaviours. Below are some samples, the rest is in the source code.

More sample usages

There are a few samples in the samples folder which shows how you can combine the different components to fit your requirements.

Samples in the wild

Feel free to add your samples to this section or let us know if you use it.

Building the source

###Preparing the workspace You will need Node/NPM and Grunt installed. Install required development dependencies:

$ cd carousel-js && npm install
$ npm install -g grunt grunt-cli
$ grunt

This runs tests and puts a new package in your local dist folder, ready to use.

Running tests

Currently all tests are run using Karma runner. Tests use the Buster assertion library and Jasmine for writing tests. Jasmine was selected due to the fact it helped us move away from JsTestDriver.

    $ npm test

    $ grunt karma

    $ ./node_module/.bin/karma start


The carousel package contains numerous components which can be packaged together to give you exactly the kind of carousel widget you want.


Some components rely on jQuery, we are working to lose those as soon as possible.

How to release

$ npm test $ npm version [ | major | minor | patch | premajor | preminor | prepatch | prerelease] $ grunt $ git push --follow-tags $ npm publish


What about AMD support?

The pieces which make up the carousel widget are not AMD modules. However if you have a look in the samples directory you can se how to use the widget in an AMD environment

Other module formats can take similar approaches. There are currently no plans to expose the individual modules in the carousel to different module formats.

I get an error with the bind function

The carousel requires an ES5 shim to be present for browsers which doesn't have the bind function available.

Original authors


Our general purpose carousel widget which can be used for multiple use-cases.





No packages published