imgZoom Home

imgZoom Documentation

Last revised: Sep 30, 2011

  1. Introduction
  2. Basic Usage
  3. Options
  4. Wrap
  5. API Methods

Introduction

ImgZoom is a jQuery plugin that implements a smooth zoom effect on images. It uses vector graphics (SVG or VML) to create a graceful transition between the thumbnail and the full-sized image.

Basic Usage

The standard way of using the plugin is with a number of thumbnail images that link to larger pictures, e.g.:

<a href="puppy.jpg"><img class="thumbnail" src="puppy_small.jpg" alt="Puppy" /></a>
<a href="kitten.jpg"><img class="thumbnail" src="kitten_small.jpg" alt="Kitten" /></a>
<a href="spider.jpg"><img class="thumbnail" src="spider_small.jpg" alt="Spider" /></a>

To enable the zooming functionality for these images, select them with a jQuery selector and call the imgZoom() method:

$(document).ready(function () {
    $('img.thumbnail').imgZoom();
});

The plugin automatically picks up the href attribute of each immediate parent element and uses it as the location of the full-size image.

If your HTML document is structured differently, i.e. the thumbnails are not wrapped in links that point to the larger versions, you can use the src option to explicitly set the location of the full-size image.

Options

The plugin can be initialized with a number of options, passed as an object to the imgZoom() method. The available options are:

Option Description
classPrefix A string that is prepended to class names assigned to plugin elements (see below for details)
default: "imgzoom"
duration The duration of the zoom in/zoom out animation (in milliseconds).
default: 500
fastSwitch If set to true, switching to the previous/next image happens without the zoom out/zoom in animation.
default: false
group If you want to have multiple groups of images on the page, and navigate them independently (using the prev/next links), use this option to set a specific name for each group.
hideThumbnail If set to true, the thumbnail image turns invisible when animation starts.
default: false
instance If set to true, the imgZoom() call returns a reference to an instance of imgZoom bound to the image, allowing you to use its API methods (see below).
loadingImg The URL of the image used as a "loading" icon, displayed on top of the thumbnail when the full-sized image is loading.
default: "css/imgzoom-loading.gif"
opacity If set to a number between 0 and 1, the image's opacity is gradually increased starting with the given value and ending with 1, producing a fade-in effect.
If set to an array of two numbers, the numbers correspond to the starting and ending opacity.
default: 1
overlayOpacity The opacity of the overlay (visible when showOverlay is true).
default: 0.75
remove If set to true, the plugin is removed.
rotate If set to true, the image does a 360° clockwise rotation while zooming in.
If set to a positive integer greater than 1, it defines the number of rotations.
If set to a negative integer, the image is rotated counter-clockwise.
default: false
showOverlay If set to true, a semi-transparent black overlay is displayed in the background of the full-size image.
default: false
src URL of the full-size image, if it's not referenced by the parent's href attribute.
title Image title that will be displayed in the wrap. If not specified, the plugin reads it from the title attribute of the anchor element containing the image, or the title of the image element itself.
wrap A block of HTML code that will be wrapped around the full-size image (see below for details).
wrapDuration The duration of the wrap fade-in animation (in milliseconds).
default: 300

You can call the plugin more than once on the same <img> element with a new set of options, and the new options will override the old ones. For example, if you set a new value for the duration option, the animation speed will be changed. The two exceptions are the src and group options -- these can only be set when the plugin is initialized.

Wrap

After the image is zoomed in to its full size, it gets wrapped in a block of HTML code that displays additional information and user interface elements, like the image's title, navigation buttons for previous and next images, and so on. The plugin provides the default wrap block – if you want to use a different one, you can set it with the wrap option.

There is a number of classes that need to be assigned to wrap block elements to define their roles. For example, if you add the imgzoom-next class to an element, then clicking it will switch to the next image. The table below lists all the classes recognized by the plugin:

Class Name Description
imgzoom-wrap The root element of the wrap block must have this class.
imgzoom-container The container element that the full-size image will be appended to. One element with this class must be present in the wrap block.
imgzoom-title The contents of this element will be set to the title of the image.
imgzoom-current The contents of this element will be set to the number of the currently displayed image.
imgzoom-last The contents of this element will be set to the number of the last image in the set.
imgzoom-prev Clicking this element will switch to the previous image in the set.
imgzoom-next Clicking this element will switch to the next image in the set.
imgzoom-close Clicking this element will close the currently displayed image.
imgzoom-width Any element with this class will have its width set to the width of the currently displayed image.
imgzoom-height Any element with this class will have its height set to the height of the currently displayed image.
imgzoom-wrap-first Automatically assigned to the element with the imgzoom-wrap class if the currently displayed image is the first one.
imgzoom-wrap-last Automatically assigned to the element with the imgzoom-wrap class if the currently displayed image is the last one.

The default wrap block has the following structure:

<div class="imgzoom-wrap imgzoom-width">
    <div class="imgzoom-container imgzoom-width imgzoom-height">
        <a href="#" class="imgzoom-prev"><span>Prev</span></a>
        <a href="#" class="imgzoom-next"><span>Next</span></a>
    </div>
    <div class="imgzoom-counter">
        <span class="imgzoom-current" />&nbsp;of&nbsp;
        <span class="imgzoom-last" />
    </div>
    <div class="imgzoom-title" />
    <div class="imgzoom-close">Close</div>
</div>

Since the plugin requires that the wrap block has an element with the imgzoom-wrap class containing one element with the imgzoom-container class, the simplest block that you can use is:

<div class="imgzoom-wrap">
    <div class="imgzoom-container" />
</div>

API Methods

A number of API methods are provided to make it easier to extend the plugin and to integrate it with other web application components.

In order to use these methods, you need an instance of the plugin's object. To get one, call the imgZoom() method with the instance option set to true:

var imgzoom = $('#thumbnail').imgZoom({ instance: true });

You can then use this object to call the public methods. For example, to start a slow (two-second) zoom of the image, you can call the zoomIn() method, passing 2000 as the parameter:

imgzoom.zoomIn(2000);

Note that you should only use the instance after the plugin has been fully initialized, i.e. in the onInit callback function, or anytime after onInit has been triggered.

The following methods are available:

Method Description
getOptions getOptions()

Get current options

Returns:
An object containing the set of options currently in use

setOptions setOptions(newOptions)

Set plugin options

Parameters:
newOptions – The new options object

zoomIn zoomIn([duration], [callback])

Zoom in to display the full-sized image

Parameters:
duration (optional) – The duration of the zoom-in animation (in milliseconds). If omitted, the duration specified in the options is used.
callback (optional) – Callback function to be executed when the animation is completed

zoomOut zoomOut([duration], [callback])

Zoom out to hide the full-sized image

Parameters:
duration (optional) – The duration of the zoom-out animation (in milliseconds). If omitted, the duration specified in the options is used.
callback (optional) – Callback function to be executed when the animation is completed