API

Auto-Initialization

Cycle2 slideshows can be automatically initialized simply by adding the classname cycle-slideshow to your slideshow container element.

<div class="cycle-slideshow" ...

Cycle2 will automatically find and initialize a slideshow for any element that contains this classname. If you do not want this behavior then do not add the cycle-slideshow class to your slideshow and instead initalize the slideshow programmatically by invoking the cycle method on the slideshow container element:

$( '.mySlideshows' ).cycle();

Auto-initialization is not supported for slideshows that are added to the DOM after jQuery's ready event has fired. In this case you will need to programatically initialize your slideshow by invoking the cycle method as shown above. You do not need to qualify your selector to the part of the DOM that has been updated as Cycle2 will not re-initialize a running slideshow if you invoke cycle on it more than once. So it is perfectly safe to run the code above multiple times without having to worry about slideshows that are already running.

Options

Options are set on the slideshow element using data-cycle-option-name attributes. The option name is always lowercase and prefixed with data-cycle-. For example, to set the speed and manual-speed options you would do this:

<div class="cycle-slideshow" data-cycle-speed="600" data-cycle-manual-speed="100"> ...

This is the preferred method of setting slideshow options as it greatly reduces (or eliminates) the need for custom initialize script.

Options can also be set programatically if you prefer, by passing an options hash to the cycle method. When setting options programmically the option name does not contain the data-cycle- prefix and the string is camelCased on hyphens:

$('.cycle-slideshow').cycle({
    speed: 600,
    manualSpeed: 100
});

All options can be declared with data-cycle-* attributes on the container element and will be inherited by all slides.

Options in the table below that have a • symbol can be overridden on individual slide elements in order to have specific properties for specific slides.

data-cycle-auto-height="600:400"

$.fn.cycle.defaults.autoSelector = '.mySlideshows';

Commands

Commands are issued to slideshows by invoking cycle on the container element and passing it a string argument, which is the command name.

var newSlide = '<img src="pic.jpg">';
$('.cycle-slideshow').cycle('add', newSlide);

$('.cycle-slideshow').cycle('destroy');

// goto 3rd slide
$('.cycle-slideshow').cycle('goto', 2);

$('.cycle-slideshow').cycle('next');

$('.cycle-slideshow').cycle('pause');

$('.cycle-slideshow').cycle('prev');

$('.cycle-slideshow').cycle('reinit');

// remove 2nd slide
$('.cycle-slideshow').cycle('remove', 1);

$('.cycle-slideshow').cycle('resume');

$('.cycle-slideshow').cycle('stop');

Declarative Commands

It is possible to issue commands declaratively by using the data-cycle-cmd attribute. You can use this attribute on any element and Cycle2 will use event delegation to issue a cycle command when the element is clicked. For example, to have a random button element pause your slideshow you can do this:

<button data-cycle-cmd="pause">Pause</button>

When the above button is clicked, Cycle2 will auto-generate and run this code for you:

$('.cycle-slideshow').cycle('pause');

To specify a specific slideshow as the target of the command, use the data-cycle-context attribute and set its value to a selector string that identifies the desired slideshow:

<button data-cycle-cmd="pause" data-cycle-context="#mySlideshow">Pause</button>

When the above button is clicked, Cycle2 will auto-generate and run this code for you:

$('#mySlideshow').cycle('pause');

And finally, you can pass an argument to the cycle command using the data-cycle-arg attribute. For example, to remove the first slide in a slideshow:

<button data-cycle-cmd="remove" data-cycle-context="#mySlideshow" data-cycle-arg="0">Remove Slide</button>

Events

Cycle2 emits numerous events as a slideshow runs and you can bind to these events in order to further customize or augment the slideshow's behavior.

All cycle events are triggered on the slideshow element and so can be bound using code like:

$( '#mySlideshow' ).on( 'cycle-eventname', function( event, opts ) {
    // your event handler code here
    // argument opts is the slideshow's option hash
});

function(event, optionHash, outgoingSlideEl, incomingSlideEl, forwardFlag)

function(event, optionHash, outgoingSlideEl, incomingSlideEl, forwardFlag)

function(event, optionHash, API)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash)

function(event, jQueryWrappedSlideEl)

function(event, indexOfSlideRemoved, removedSlideEl)

function(event, optionHash)

function(event, optionHash)

function(event, optionHash, slideOptionsHash, currentSlideEl)

Miscellaneous Bits

State

The Cycle2 options hash contains all of the slideshow's options detailed above, along with the following additional pieces of run-time state.

State data is read-only.

Testing the Paused State

Cycle2 assignes the class cycle-paused to the slideshow container when the slideshow is paused. Scripts can determine if the slideshow is currently paused using code like this:

var paused = $('#mySlideshow').is( '.cycle-paused' );

hash

Each slide in your slideshow can have an attribute named data-cycle-hash. If you assign a value to this attribute then the location hash of the current page will be updated to reflect that value when the slide is active. Likewise, when the page is loaded if the location hash is equal to the data-cycle-hash of one of the slides then that slide will be made active. See the Bookmarkable demo for more information.