About jQuery SlideShow

jQuery Slideshow

The last slideshow you'll ever need.

View the demos, they're radical.

This documentation is released under the Creative Commons - Attribution-NonCommercial-ShareAlike license.

Cheat Sheet

HTML

<!-- styling the height and width is important for some transitions -->
<div id="slideshow" style="width: 400px; height: 200px">
  <img src="../img/one.jpg"> <!-- can use any element you want, not just images -->
  <img src="../img/two.jpg">
  <img src="../img/three.jpg">
  <img src="../img/four.jpg">
  <img src="../img/five.jpg">
</div>

CSS

Generally you want your slides to be 100% width and height of the slideshow, but you can do whatever you want.

JavaScript

var $el = $('#slideshow');
$el.slideshow({
  duration: 400,
  delay: 3000,
  selector: '> img',
  transition: 'push(up)',
  autoPlay: true,
  show: function (params){
    var nextIndex = params.next.index;
    if (nextIndex > 2) {
      // do something awesome when the slide is after the third slide.
    }
  },
  complete: function (params){
    // do something awesome when a transition finishes
  }
});

// get the slideshow object if you want it
var slideshow = $el.data('slideshow');

// show the third slide
$el.slideshow( 'show', 2 ); // Element API
slideshow.show(2); // object API

// show the next slide
slideshow.show('next');

// pause and play
slideshow.stop();
slideshow.play();

Custom transitions

You can create your own transitions :D

jQuery.rf.slideshow.defineTransition('slide', function (params, dir, ease){
  var animation = {},
      prop = (dir == 'left' || dir == 'right') ? 'left' : 'top';
  animation[prop] = (dir == 'left' || dir == 'up') ? '-100%' : '100%';
  params.previous.animate(animation, params.duration, ease);
});

The name of a transition works like a function, but it's just a string. You can allow for any number of arguments when creating a transition.

For instance, with the slide example, the acceptable transition options could be:

'slide(left)'
'slide(right)'
'slide(up)'
'slide(down)'
'slide(left, linear)'
'slide(left, bounce)'
// in other words
'slide([direction], [easing])'

jQuery.rf.slideshow

jQuery.fn method: slideshow

jQuery UI constructor/element bridge that creates a new slideshow instance on the set of matched elements and stores it on the slideshow key of the element' data. All instance methods and properties are available through the jQuery wrapper API from the jQuery widget factory bridge.

Signatures

.slideshow(options)
.slideshow(method, [methodArg [, methodArgN]])
.slideshow(property [, value])

Arguments

  1. options (object) - Key value pairs of options, see jQuery.rf.slideshow for more information.
  1. method (string) - The method name as a string to call on the slideshow instance
  2. methodArg (mixed) - The argument(s) to send to the method
  1. property (string) - The property name to get or set from the slideshow instance (will get if value parameter is omitted)
  2. value (mixed) - The value to set the property to on the slideshow instance

Returns

Object - A jQuery object

Examples

var el = $('#slideshowElement')

// create an instance of slideshow with a few options
el.slideshow({
  selector: 'img',
  delay: 5000,
  duration: 500,
  transition: 'fadeThroughBackground'
});

// call a method through the jQuery UI bridge API
el.slideshow('show', 2); // shows the third slide

// get the instance out of the elements data
var slideshow = el.data('slideshow');

// call methods directly on the instance
slideshow.show(2);

slideshow constructor: jQuery.rf.slideshow

The slideshow constructor function created by jQuery UI widget factory.

Signature

new jQuery.rf.slideshow(options, node)

Arguments

  1. options (object) - An object map of key value pairs
    • transition (string, default 'fade' ) - The default transition to use. Slideshow ships with: push, slide, blind, fade, crossFade, fadeThroughBackground, and none. Read more about transitions
    • selector (css selector string, default '> *') - A CSS selector that defines which children elements are the slides. The default selects immediate children.
    • initialIndex (number, default 0) - Which slide to show upon on initialization by index.
    • autoPlay (boolean, default false) - Automatically cycles the slideshow without having to call the play method.
    • delay (number, default: 3000) - The time in milliseconds a slide is displayed.
    • duration (number, default: 400) - The time in milliseconds a transition animates.
    • resetTimerOnShow (boolean, default: true) - If true, when show is called while the slideshow is playing, the delay timer is reset. If false, calling show does not interrupt the timer and you will get two transitions (or more) for one delay cycle.
    • autoStyle (boolean, default: true) - Automatically sets the style properties on your elements that most transitions need: { left: 0, top: 0, position: 'absolute' } for slides and position relative for the parent element if position is static.
  2. node (element) - A DOM element (not a jQuery wrapped collection)

Returns

Object A slideshow instance object.

Examples

// generally, jQuery widgets don't do it like this :P
var slideshow = new jQuery.rf.slideshow({
  transition: 'push(left, swing)',
  selector: '.slide'
}, $('#slideshow)[0]);

// if you want an object to work with this is more jQuery-esque...
var slideshow = $('#slideshow').slideshow({
  transition: 'push(left, swing)',
  selector: '.slide'
}).data('slideshow');

slideshow function: defineTransition

Defines a slideshow transition, the muscle behind slideshow. I encourage you to read the source where the out-of-the-box transitions are defined. Mastering this function will allow you to flippin' sweet slideshows.

Signature

jQuery.rf.slideshow.defineTransition( name, transition )

Arguments

  1. name (string) - The name of the transition.
  2. transition (function) - The function called when the slideshow uses the transition.

    Signature

    function ( params [, argN] )

    Arguments

    1. params (object) - Information about the transition and slideshow instance:
      • previous ($element) - The previous slide, already wrapped with jQuery.
      • next ($element) - The next slide, already wrapped with jQuery.
      • duration (number) - The duration of the transition.
      • instance (object) - The slideshow instance, for convenience.
    2. argN (mixed) - Transition names are actually quasi-functions that take parameters that get passed through as arguments to the transition function. See examples for details.

Returns

undefined

Examples

// fade is about simplest transition
jQuery.rf.slideshow.defineTransition('fade', function( params ){
  // the previous slide is on top with z-index 1, and the next slide has z-index 0
  // ... so we can simply fade the previous slide out and use the params.duration
  params.previous.fadeOut( params.duration );
});

// The slide transition is a bit more complex
jQuery.rf.slideshow.defineTransition('slide', function ( params, direction, fade, ease ){
  // You can pass arguments to a transition (so cool)
  // direction, fade, and ease all come from the transition option the user defines
  var animation = {}, // animation options to build up
      // figure out which property to animate based on the direction
      prop = ( direction === 'left' || direction === 'right' ) ? 'left' : 'top';
  // set the animation property and value
  animation[prop] = ( direction === 'left' || direction === 'up' ) ? '-100%' : '100%';
  // check the fade argument and add opacity to the animation
  if (fade) animation.opacity = 0;
  // perform the animation and slide the previous element out
  params.previous.animate( animation, params.duration, ease );
});

// and the usage:
$('#el').slideshow({
  transition: 'slide(left, true, linear)' // here's where the arguments come from
});

Notes

As you can see from the examples, transition strings get parsed like functions and pass the values into the transition. The values true, false, null, undefined and '' values will be converted to their primitive types.

slideshow method: show

Transitions from the current slide to another.

Signature

slideshow.show( what, options )
$element.slideshow( 'show', what, options )

Arguments

  1. what (mixed) - Accepts the strings 'next' and 'previous' or the index of the slide you want to show, ie: 2
  2. options (object) - Can override the instance options duration and transition for just this transition.

Returns

Object Returns the slideshow object or the jQuery collection.

Examples


var $element = $('#slideshow').slideshow(); // create slideshow, store element
var slideshow = $element.data('slideshow'); // get slideshow instance

// show 3rd slide
$element.slideshow( 'show', 2 ); // $element API
slideshow.show( 2 ); // object API

// show next slide
$element.slideshow( 'show', 'next' ); // $element API
slideshow.show( 'next' ); // object API

// show previous slide with options
$element.slideshow( 'show', 'next', {
  transition: 'push(right)',
  duration: 1000
}); // $element API

slideshow.show( 'next', {
  transition: 'push(right)',
  duration: 1000
}); // object API

slideshow method: play

Transitions slides on an interval defined in options.delay.

Signature

slideshow.play()
$element.slideshow( 'play' )

Returns

Object Returns the slideshow object or the jQuery collection.

Examples


var $element = $('#slideshow').slideshow(); // create slideshow, store element
var slideshow = $element.data('slideshow'); // get slideshow instance

$element.slideshow( 'play' ); // $element API
slideshow.play(); // object API

slideshow method: stop

Stops the slideshow when cycling.

Signature

slideshow.stop()
$element.slideshow( 'stop' )

Returns

Object Returns the slideshow object or the jQuery collection.

Examples


var $element = $('#slideshow').slideshow(); // create slideshow, store element
var slideshow = $element.data('slideshow'); // get slideshow instance

$element.slideshow( 'stop' ); // $element API
slideshow.stop(); // object API

slideshow property: element

$element - The jQuery wrapped slideshow element

slideshow.element
$element.slideshow( 'element' )

slideshow property: slides

Array - The jQuery wrapped slide elements.

slideshow.slides
$element.slideshow( 'slides' )

slideshow property: current

Number - The index of the current slide.

slideshow.current
$element.slideshow( 'current' )

slideshow property: playing

Boolean - True if playing.

slideshow.playing
$element.slideshow( 'playing' )

slideshow property: transitioning

Boolean - True if in the middle of a transition.

slideshow.transitioning
$element.slideshow( 'transitioning' )

slideshow event: show

Fires when the slideshow starts a transition.

Signature

function( event, eventData )

Arguments

  1. event (null) - I'm honestly not sure why this exists for widget custom events :\
  2. eventData (object) - Data about the event
    • next (object) - Information about the next element.
      • element ($element) - The next element, wrapped by jQuery.
      • index (number) - The index of the next slide.
    • previous (object) - Information about the previous element.
      • element ($element) - The previous element, wrapped by jQuery.
      • index (number) - The index of the previous slide.
    • instance (object) - The slideshow instance.

Examples

// element API, can pass in as an option
var $el = $('#slideshow').slideshow({
  show: function ( event, eventData ){
    // do something with eventData
    if (event)
  }
});

// or can add it later
var slideshow = $el.data('slideshow'); // get the instance
slideshow.bind('slideshowshow', function(){
  // do something
});

slideshow event: complete

Fires when a slideshow transition ends.

Signature

function( event, eventData )

Arguments

  1. event (null) - I'm honestly not sure why this exists for widget custom events :\
  2. eventData (object) - Data about the event
    • next (object) - Information about the next element.
      • element ($element) - The next element, wrapped by jQuery.
      • index (number) - The index of the next slide.
    • previous (object) - Information about the previous element.
      • element ($element) - The previous element, wrapped by jQuery.
      • index (number) - The index of the previous slide.
    • instance (object) - The slideshow instance.

Examples

// element API, can pass in as an option
var $el = $('#slideshow').slideshow({
  complete: function ( event, eventData ){
    // do something with eventData
    if (event)
  }
});

// or can add it later
var slideshow = $el.data('slideshow'); // get the instance
slideshow.bind('slideshowcomplete', function(){
  // do something
});

slideshow css: next

During a transition, the next element gets the CSS class .slideshow-next.

slideshow css: previous

During a transition, the previous element gets the CSS class .slideshow-previous.

slideshow css: current

The current slide gets the css class .slideshow-current.

slideshow css: transitioning

During a transition, the slideshow element gets the css class .slideshow-transitioning.

jQuery.rf.slideshownav

jQuery.fn method: slideshownav

jQuery UI constructor/element bridge that creates a new slideshow instance on the set of matched elements and stores it on the slideshow key of the element' data. All instance methods and properties are available through the jQuery wrapper API from the jQuery widget factory bridge.

Signatures

.slideshownav(options)
.slideshownav(method, [methodArg [, methodArgN]])
.slideshownav(property [, value])

Arguments

  1. options (object) - Key value pairs of options, see jQuery.rf.slideshow for more information.
  1. method (string) - The method name as a string to call on the slideshow instance
  2. methodArg (mixed) - The argument(s) to send to the method
  1. property (string) - The property name to get or set from the slideshow instance (will get if value parameter is omitted)
  2. value (mixed) - The value to set the property to on the slideshow instance

Returns

Object - A jQuery object

Examples

var el = $('#slideshowElement')

// create an instance of slideshownav with a few options
el.slideshow({
  navSelector: '.nav',
  mode: 'vertical'
});

// call a method through the jQuery UI bridge API
el.slideshownav('show', 2); // shows the third slide

// get the instance out of the elements data
var slideshow = el.data('slideshownav');

// call methods directly on the instance
slideshow.show(2);

slideshownav constructor: jQuery.rf.slideshownav

The slideshownav constructor function created by jQuery UI widget factory.

Signature

new jQuery.rf.slideshownav(options. node)

Arguments

  1. options (object) - An object map of key value pairs
    • All the options of jQuery.rf.slideshow plus the following:
    • navSelector (string, default '> ul > li > a' ) - A CSS selector that defines which elements represent the navigation for the slides.
    • mode (string, default horizontal) - Which direction the navigation items are relative to each other. Relevant because slideshownav dynamically figures out if a transition should be 'up' or 'down' and 'right' or 'left'.
    • navTransition (string, default 'push(#{direction})') - Called when navigation items are clicked. The #{direction} "variable" will be replaced with 'up', 'down', 'left', or 'right' depending upon the mode and previous/next slides. Do read the notes in this section.
  2. node (element) - A DOM element (not a jQuery wrapped collection)

Returns

Object A slideshow instance object.

Examples

// generally, jQuery widgets don't do it like this :P
var slideshow = new jQuery.rf.slideshownav({
  navTransition: 'push(#{direction}, swing)', // direction will be dynamically changed to 'left' or 'right'
  mode: 'horizontal',
  navSelector: '.nav'
}, $('#slideshow)[0]);

// if you want an object to work with this is more jQuery-esque...
var slideshow = $('#slideshow').slideshow({
  navTransition: 'push(#{direction}, swing)',
  mode: 'horizontal',
  navSelector: '.nav'
}).data('slideshow');

Notes

When a transition starts, slideshownav looks at the mode and then does some math with the previous and next slide indices and then passes that knowledge into the transition arguments. For example: if a slideshow's mode is horizontal and the transition is 'push(#{direction})', and it's moving from the first slide to the second slide, it will replace #{direction} with 'left', and the transition becomes push(left).

slideshownav event: click

Triggered when a nav element is clicked.

slideshownav css: current-nav

A CSS class applied to the current navigation element.

slideshownav css: next-nav

During a transition, the next navigation element gets this CSS class

slideshownav css: previous-nav

During a transition, the previous element gets this CSS class.