SimpleZoom: A jQuery Plugin for Magnifying Images (ver.0.2.2)

posted Jul. 29, 2012 by Kraig Halfpap under JavaScript


This post refers to an old version of the SimpleZoom plugin. For the latest version of this plugin check out /blog/tag/simplezoom.

In my inaugural blog post I introduced a jQuery plugin for magnifying images named SimpleZoom. The purpose of this post is to introduce the updated SimpleZoom v.0.2.2 which adds new options and greatly simplifies the invocation process.

The SimpleZoom plugin is intended to be invoked upon an <img> element for which a corresponding higher resolution image resource is available. This higher resolution image, which is provided to the plugin via its URL, then acts as the magnified image. Of course, invocation need not follow this specific pattern. Indeed, the plugin may be invoked upon any DOM element while specifying any image resource desired.

Once initialized, the SimpleZoom plugin creates a user controlled viewfinder widget which is used to designate a portion of the magnified image to be displayed within the plugins viewport widget. By default, the viewport and viewfinder widgets are combined to give the impression of a single "magnifying lens" widget. Alternatively, a separate DOM element may be specified as the plugins active viewport.

Tested for compatibility with jQuery versions 1.9.1, 1.8.2, 1.8.0 and 1.7.2 on most major browsers going back to IE7.

View Demo


The SimpleZoom plugin may be invoked in the following manner.

  • JavaScript
$(target).simpleZoom(src, options);
Argument Type Required? Description
target jQuery Object/Selector or DOM Element Yes <img> element or any fixed dimensional element with a set background-image.
src String Yes Specifies the URL of an existing image resource to be displayed within the plugins viewport widget. This image resource is intended to be a higher resolution version of the target image.
options Object or JSON String No This optional argument may be used to specify additional parameters in a key-value pair format. A complete listing of valid parameters can be found in the options section below.

The SimpleZoom plugin may be invoked at any point after the target element appears within the document. Indeed, it is not necessary to wait for any of the associated image resources to load.

Utility Functions

When the SimpleZoom plugin is invoked within a dynamic webpage, situations may arise in which the plugin may need to be "refreshed" in order to continue functioning properly. Such is the case when the target element is dynamically resized or translated. In these instances, the plugin can be notified of possible changes by calling a special refresh utility function. An object with references to the refresh and other utility functions are returned by the SimpleZoom plugin when 'returnUtil' : true is specified as a parameter of the options argument.

  • JavaScript
var options =  {'returnUtil' : true};
var utilities = $('#small-img').simpleZoom(src, options);
utilities .refresh();

The following table details the existing utility functions.

Function NameReturn TypeDescription
refreshBooleanCorrects the positioning of the viewfinder widget to take into account any changes in the size or position of the target element and returns a boolean value indicating the success or failure of the call. Note that this function is invoked automatically whenever the window is resized.
destructBooleanRemoves the associated plugin instance completely and returns a boolean value to indicate success or failure.


Included in the SimpleZoom download package is a stylesheet named simplezoom.css. This is the primary stylesheet for the plugin and must be present in order for it to function. Entries in the stylesheet listed under the 'Customizable CSS' header may be edited and expanded upon. For example, the width, height and border-radius of the combined viewfinder/viewport (magnifying lens) widget may be altered by editing rules for the SZ-zoom CSS class.

The following table details the CSS classes used by the SimpleZoom plugin.

CSS Class Description
SZ-zoom Assigned to the combined viewfinder/viewport (magnifying lens) widget. This class entry may be edited to specify custom dimensions for the widget.
SZ-fullAssigned to the fullscreen image widget when the fullscreen option is enabled.
SZ-close Assigned to the "exit" button which appears when in fullscreen image mode.
SZ-backdropAssigned to the backdrop which appears behind the fullscreen image widget.
SZ-viewfindAssigned to the standalone viewfinder widget which takes the place of the magnifying lens widget (.SZ-zoom) when a separate viewport is specified as an options parameter . Note that the dimensions of the viewfinder widget determined by the size of the provided viewport element and therefore need not be specified.


Custom options may be specified for the SimpleZoom plugin as a collection of key-value pairs. Such a collection may be constructed as either a standard Object or a JSON String, and then passed to the SimpleZoom plugin as the secondary argument.

The following table details the valid parameters of the options object.

fadeDurationUnsigned Long250Specifies the duration, in milliseconds, of the fade-in and fade-out animations of the viewfinder widget.
smoothingFloat0.35Controls how quickly the viewfinder widget moves to a new cursor or touch event position. The value specified should be on the range (0, 1), with larger values corresponding to a faster convergence of the magnifying lens widget to the event position.
fillBooleantrueDetermines whether or not the magnified image fills up the viewport when viewing the edges of the target element.
confineBooleanfalseWhen set to true, the viewfinder widget is confined within the boundary of thetarget element.
viewportjQuery Object/Selector or DOM ElementnullSets the plugins active viewport in which the magnified image (i.e., the image resource specified by the src argument) is displayed. When specified, the magnifying lens widget is replaced by a transparent viewfinder widget, which is assigned a CSS class of SZ-viewfind. Note that the dimensions of the viewfinder widget are automatically calculated, and therefore should not be explicitly specified within the simplezoom.css sytlesheet.
mobileBooleanfalseEnables mobile touch screen compatibility mode. Note that enabling this option does not actually add any additional functionality for touch screen browsing.
fullscreenBooleanfalseWhen set to true, clicking on the target element will display a fullscreen version of the src image. The image will be sized in order to fit within the window.
fullPaddingFloat15Specifies the minimum padding, in pixels, between the fullscreen image and the window.
fullTransUnsigned Long350Specifies the duration, in milliseconds, of the fade-in and fade-out animations for the fullscreen image.
disableContextBooleanfalseMay be specified to disallow the context menu.
returnUtilBooleanfalseWhen set to true, instead of returning this, the SimpleZoom method will return an object with references to the utility functions refresh and destruct.
onloadFunctionnullSpecifies a function to be executed once the image resources associated with a particular invocation of SimpleZoom have been loaded.
completeFunctionnullSpecifies a function to be executed once SimpleZoom has been initialized.


Mouseover or tap the image below.

Winter Lake Digital Painting by Kraig Halfpap
  • Example #1
  • Example #2