jQuery ImageSwitch Plugin

DESCRIPTION

The plugin is used to perform switch animations between two overlapping images. The plugin was originally developed for a demonstration to switch between two icons in different style as can be seen here.

FEATURES

different switch animation effects
switch on mouse hover
sequential switch on multiple images
switching between two transparent images

FILE STRUCTURE

/examples                 -> folder with fully working examples
  /imgs                   -> images used for examples
    ...
  /jquery                 -> jQuery sources
    ...
  all_examples.html       -> all examples
  animation_queue         -> example with multiple queued animations
  animations.html         -> basic animation example
  hover.html              -> mouse hover example
/src              
  jquery.imageswitch.js   -> ImageSwitch jQuery plugin file
README.md                 -> this readme file

MINIMAL EXAMPLE

This is a minimal example of an HTML page with 3 overlapping images which crossfade from one image to the other when the mouse hovers over the images.

<!DOCTYPE html>
<html>
  <head>
    <script src="jquery.js" type="text/javascript"></script>
    <script src="jquery.imageswitch.js" type="text/javascript"></script>

    <script>
      $(document).ready(function() {
        $('.image_switch').imageSwitch('hover');
      });
    </script>

    <style>
      .image_switch {
        position: relative;
        width: 128px;
        height: 128px;
      }
      .image_switch img {
        position: absolute;
        top: 0;
        left: 0;
      }
    </style>
  </head>
  <body>
    <div class="image_switch">
      <img src="example_bottom_image_1.png" />
      <img src="example_top_image_1.png" />
    </div>

    <div class="image_switch">
      <img src="example_bottom_image_2.png" />
      <img src="imgs/example_top_image_2.png" />
    </div>
    
    <div class="image_switch">
      <img src="example_bottom_image_3.png" />
      <img src="example_top_image_3.png" />
    </div>
  </body>
</html>

SETUP

Script

To setup the ImageSwitch plugin simply include the javascript file in the of your document <script type="text/javascript" src="jquery.imageswitch.js"></script>

You will also need to include jQuery

<script type="text/javscript" src=""jquery.js"></script>

Markup

Place the top and bottom image in a surrounding div.

<div class="switch_image">
  <img src="imgs/bottom_image.png" />
  <img src="imgs/top_image.png" />  
</div>

You can also nest the images inside this structure, e.g. by surrounding anchor tags.

<div class="switch_image">
  <a href="#"><img src="imgs/bottom_image.png" /></a>
  <a href="#"><img src="imgs/top_image.png" /></a>
</div>

If you would like to use background images instead you need to declare classes 'imageBottom' and 'imageTop' for the top and bottom images.

<div class="switch_image">
  <div class="imageBottom" style="background: url('imgs/bottom_image.png')"></div>
  <div class="imageTop" style="background: url('imgs/bottom_image.png')"></div>
</div>

Style

The two top and bottom image must completely overlap. A basic way to achieve this is

<style>
  .switch_image {
    position: relative;
  }
  .switch_image img:first-child {
    position: absolute;
    top: 0;
    left: 0;
  }
</style>

BASIC USAGE

To switch from the top image to the bottom image you can simply call:

$(selector).imageSwitch('bottom');

To switch back to the top image call:

$(selector).imageSwitch('top');

There are a couple of options to customize the animation which you can pass as a map:

$(selector).imageSwitch('bottom', {
  transformation: 'slide'
  duration: 500
})

To switch from either bottom or top state to the other state use the toggle action:

$(selector).imageSwitch('toggle');

It is possible to queue the animations. The following will toggle from one state to the other and back:

$(selector).imageSwitch('toggle').imageSwitch('toggle');

The same behavior can be achieved by the blink action (toggles twice):

$(selector).imageSwitch('blink');

To animate a blink (works also for toTop, toBottom, toggle) action on multiple images one by one in a sequence order you may set the sequence option:

$(selector).imageSwitch('blink', { sequence: true });

To animate to the bottom image when the mouse hovers over and back to the top image when the mouse hovers out do:

$(selector).imageSwitch('hover');

All methods can be customized by a couple of options. To set all calls on the same jQuery object with the same options you can apply the init action:

$(selector).imageSwitch('init', {
  transformation: 'fade',      
  duration: 2000,
  easing: '',
  queue: 'my own queue'
});

The init function can be queued just like any other action:

$(selector)
  .imageSwitch('bottom')                  // switch to bottom in 1000 milliseconds default time 
  .imageSwitch('init', { duration: 500 }) // init animation time for all future calls
  .imageSwitch('top')                     // switch to top in 500 milliseconds

This is just a small overview of what's possible with this plugin. See the API reference below to get the complete picture.