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:

View and move multiple panes.

Toggle full pagination.

Customise transition speed, easing, and pane delay.

Toggle looped movement.

Toggle display of controls on hover.

Toggle pause when hovered.

Potential for custom transitions.

A multitude of namespaced custom events that allow you to bind your
own behaviour.

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.

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

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.{functionname}

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.