Modern Carousel

Introduction

This carousel widget for jQuery makes use of modern CSS to keep panels within the normal flow of the document. This means there are no positional calculations required in the JavaScript, and no float clearing in the CSS.

Features include:

Source

You can find the source, including demos, on GitHub at:

http://github.com/nefarioustim/modern-carousel/

Basic implementation

To implement a carousel like the example above, you’ll need to do the follow:

Include the JavaScript and CSS assets

<link rel="stylesheet" href="/a/c/carousel.core.css" type="text/css">
<link rel="stylesheet" href="/a/c/carousel.skin.css" type="text/css"><script type="text/javascript" src="/a/j/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="/a/j/jquery.easing.min.js"></script>
<script type="text/javascript" src="/a/j/jquery.carousel.2.1.min.js"></script>

Both the carousel.skin.css and jquery.easing.min.js files above are entirely optional.

The skin file provides styling for the controls (as seen above). You can, of course, choose to style these however you wish; the controls are rendered in two lists straight after the .clip element.

The easing script provides the standard jQuery Easing plugin, as supplied as part of jQuery UI.

Insert the widget HTML

Next step is to insert your HTML. The example above is as follows:

<div class="carousel skin" id="example1">
    <div class="clip">
        <ul class="horizontal">
            <li><img src="/a/i/family.png" alt="Family" width="220" height="220"></li>
            <li><img src="/a/i/luxury.png" alt="Luxury" width="220" height="220"></li>
            <li><img src="/a/i/romantic.png" alt="Romantic" width="220" height="220"></li>
            <li><img src="/a/i/spa.png" alt="Spa" width="220" height="220"></li>
            <li><img src="/a/i/family.png" alt="Family" width="220" height="220"></li>
            <li><img src="/a/i/luxury.png" alt="Luxury" width="220" height="220"></li>
            <li><img src="/a/i/romantic.png" alt="Romantic" width="220" height="220"></li>
            <li><img src="/a/i/spa.png" alt="Spa" width="220" height="220"></li>
            <li><img src="/a/i/family.png" alt="Family" width="220" height="220"></li>
            <li><img src="/a/i/luxury.png" alt="Luxury" width="220" height="220"></li>
            <li><img src="/a/i/romantic.png" alt="Romantic" width="220" height="220"></li>
            <li><img src="/a/i/spa.png" alt="Spa" width="220" height="220"></li>
        </ul>
    </div>
</div>

The carousel and clip classes and elements are important. Without these, the carousel will not render or function. The horizontal class can be replace with vertical for a vertically moving carousel.

Each pane in the carousel is an li in the main ul.

Define size and layout

In your own CSS, define the size and layout of your carousel. The most important element here is clip as it is used when calculating the movement between panes. If you are using a horizontal carousel, make sure you have defined a width. If, however, you are using a vertical carousel, make sure you have defined a height.

Once again, here’s the specific CSS for the example above:

#example1 {
    height: 232px;
    margin: 20px auto;
    width: 458px;
}
#example1 .clip {
    border: 1px solid #ccc;
    height: 230px;
    width: 456px;
}
#example1 .clip>ul>li {
    padding: 5px 4px;
}

Configure and instantiate the carousel

The final step is to create a configuration object and pass it to the .carousel() method of any jQuery object, which has been added by the plug-in.

For the demo above, I have included all the available configuration options. In a real-world implementation, you could skip any values where you wish to use the default:

$(document).ready(function docReady(e) {
    $('#example1').carousel({
        visiblePanes: 2, // Default: 1
        panesToMove: 2, // Default: 1
        pagination: true, // Default: true
        speed: 1000, // Default: 200
        easing: "easeInOutElastic", // Default: "swing"
        loop: true, // Default: false
        autoplay: false, // Default: false
        hovercontrols: true, // Default: false
        hoverpause: true, // Default: false
        delay: 2000, // Default: 2000
        transition: false // Default: false
    });
});

For a more detailed explanation of the configuration options, please read the table below.

Configuration options

The following options may be defined in the configuration object passed to the $(element).carousel() constructor:

Parameter Data type Default Description
visiblePanes Number 1 This is the number of panes visible in your styled carousel. Used in conjunction with the width of the `.clip` element to calculate the distance required to animate during transition.
panesToMove Number 1 This is the number of panes that will move with each activation of next or previous. This means it is perfectly possible to have 2 panes visible but move only one at a time, should that be what is required.
pagination Boolean true This flag will create a pagination ul when set to true. The pagination controls will appear with the standard controls, directly after the .clip element.
speed Number 200 The number of milliseconds the transition animation should last for.
easing String "swing" The easing method to use on the transition animation.
loop Boolean false This flag causes the carousel to loop once the final pane has been reached.
autoplay Boolean false When set to true, the carousel will automatically start to animate once instantiation is complete.
hovercontrols Boolean false If active, the controls will only show when the carousel is hovered over.
hoverpause Boolean false If active, the carousel will pause playing when the carousel is hovered over.
delay Number 2000 The number of milliseconds to pause on each pane of the carousel when playing.
transition Function reference or false false A reference to a transition function defined at $.fn.carousel. E.g. “yourTransitionHere” would reference a function defined at $.fn.carousel.yourTransitionHere.

Custom events

The following namespaced jQuery custom events are available for you to bind your own methods to:

Event name Description
play.carousel This event is triggered when the carousel is set to play. This includes the use of the autoplay configuration option.
pause.carousel This event is triggered when the carousel is paused. It is also triggered if the hoverpause configuration option is set to true, and the carousel is hovered over.
prev.carousel This event is triggered when the "previous" control is activated. Note: This event also triggers the pause.carousel event.
next.carousel This event is triggered when the "next" control is activated. Note: This event also triggers the pause.carousel event.
move.carousel This event is triggered when the carousel pane is moved by a given number of panes, and is used by several other events. Also triggered by play.carousel, prev.carousel, and next.carousel. The event callback can accept a single parameter; a signed-integer denoting the number of panes to move by.
jump.carousel This event is triggered when moving the carousel to a specific pane. It is subsequently fired by move.carousel. The callback accepts two parameters: an unsigned integer representing the pane to jump to, and another unsigned integer representing the current pane.
nav-state.carousel This event is triggered when the carousel checks the current navigation state to activate/deactivate the relevant controls. It is triggered once the carousel initialisation is complete, and after each animation between panes.

Custom transitions

The carousel widget includes a basic framework to allow you to create your own custom transitions between panes. Further to this, the script also includes a built in transition entitled fade.

Demo

When a custom transition is specified in the carousel configuration, the script will look for a corresponding function in the following namespace:

$.fn.carousel.{function name}

So, in the example of the fade transition, it is defined as:

$.fn.carousel.fade = function(config) {
    // Transition code here
}

Transition configuration argument

Each custom transition method should expect a configuration object containing the following parameters:

Parameter Description
carousel A reference to the parent carousel jQuery object.
defaults A reference to the defaults member of the parent carousel jQuery object. This object will contain each of the variables defined in the configuration options table above.
delta The calculated delta between panels.
last A number representing the pane the transition is to move away from. The first pane in the carousel would be represented as 0.
current A number representing the pane the transition is moving to. Once again, the first pane in the carousel would be represented as 0.
anim An object of standard animation configuration options to be used by animations between panels. This includes the speed and easing options set in the carousel configuration.
© 2010 Tim Huegdon - This website contains no gluten.