Cloud Zoom Quick Start Guide

It's really easy to use Cloud Zoom on your website. Just include the scripts and CSS files and call the quickStart() function.

Depending on where you place the Cloud Zoom files, you may need to change the following CSS classes so their images point to the correct path:

  • .cloudzoom-blank
  • .cloudzoom-ajax-loader

Example Web Page

Here is an example page that creates a single Cloud Zoom.

<!DOCTYPE html>

        <title>Cloud Zoom</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

        <!-- Include jQuery. -->
        <script type="text/javascript" src=""></script>

        <!-- Include Cloud Zoom CSS. -->
        <link rel="stylesheet" type="text/css" href="cloudzoom.css" />

        <!-- Include Cloud Zoom script. -->
        <script type="text/javascript" src="cloudzoom.js"></script>

        <!-- Call quick start function. -->
        <script type="text/javascript">
        <!-- Setup the zoomImage property to point to the big image. -->
        <img class = "cloudzoom" src = "images/small/image1.jpg"
             data-cloudzoom = "zoomImage: 'images/large/image1.jpg'" />


If you would like to wrap a link around the image, Cloud Zoom will use the link's href attribute as the source of the big image instead of the zoomImage property:

<a href = "images/large/image1.jpg">
    <img class = "cloudzoom" src = "images/small/image1.jpg"/>


Various properties are available to change the look and feel of Cloud Zoom.

Cloud Zoom properties can be specified in the data-cloudzoom attribute, example:

data-cloudzoom = "zoomImage: '/mypath.jpg', useZoom: '#zoom1'"

Text values/strings should be surrounded by quotes e.g. useZoom: '#myZoom'. Numbers, true and false, should not e.g. zoomFlyOut: false

Note: Older versions of Cloud Zoom (prior to 2.1 rev 1210171228) required the properties to be in strict JSON format. This will still work, but is now a deprecated.

Property NameTypeDescriptionDefault Value
zoomImagestringPath to the zoom image. If no zoom image is specified, the small image (as specifed in the image element) will be used.""
tintColorstringColor to use for the tint effect#fff
tintOpacitynumberOpacity of tint 0-1. If zero, no tint will be visible.0.25
animationTimenumberDuration of the animation effects in milliseconds.500
lensClassstringCSS class to use for lens.cloudzoom-lens
easeTime (DEPRECATED V3.0)numberNumber of milliseconds of mouse easing movement of zoom image. The bigger the number, the more easing. Zero means no easing. 500
zoomMatchSize - DEPRECATED (see zoomSizeMode)booleanAutomatically sizes the zoom image to match the page image.false
zoomPositionnumber | stringSpecifies position of zoom window. If numeric (0-15), position is relative to page image as shown by the following key (blue squares represent zoom window):

If a string is supplied, value will be used as a selector to pinpoint the exact position and size of an element in the page.

If the value "inside" is specified, the zoom image will appear inside the page image. From 3.0 rev 1303151613 you will probably want to set zoomOffsetX: 0

zoomOffsetXnumberAllows you to fine tune horizontal position of zoom.
From 3.0 rev 1303151613 also works in 'inside' mode
zoomOffsetYnumberAllows you to fine tune vertical position of zoom.
From 3.0 rev 1303151613 also works in 'inside' mode
zoomFullSize DEPRECATED (see zoomSizeMode)booleanZoom window appears at full size of zoom image.false
zoomFlyOutbooleanTurns 'flying' zoom animation on or off.true
zoomClassstringCSS class to use for zoom window.cloudzoom-zoom
zoomInsideClassstringCSS class to use for zoom window when "inside" has been used for zoomPosition.cloudzoom-zoom-inside
zoomSizeModestring Defines the rule for sizing the zoom window and lens.
  • "lens" - CSS of lens (.cloudzoom-lens) has priority, zoom window will be adjusted
  • "zoom" - CSS of zoom window (.cloudzoom-zoom) has priority, lens will be adjusted
  • "full" - Zoom window will maximise to full size of zoom image
  • "image" - Zoom window will match small image
captionSourcestringSpecify an HTML attribute in the page image to be used as text for the caption. Otherwise, specify a selector to some HTML content to use for the caption, or 'none' to switch off captions.title
captionTypestringSpecify caption type, either "attr" or "html".attr
captionPositionstringPosition of caption, "top" or "bottom".top
uriEscapeMethodboolean | stringUse of special characters or spaces in paths to images is not recommended. However, sometimes you may not have control over this. You can specify a character escape method for the image paths. Specify the JavaScript escaping method to use, either "escape" or "encodeURI" (false = no escaping).false
errorCallbackfunctionSpecify a function to call when an error occurs. Your function will receive an error object with the following properties:
  • type: string name of error, currently only "IMAGE_NOT_FOUND"
  • $element: Cloud Zoom enabled element that generated error
  • data: data associated with the error, e.g. file path of not found image
You can set up a global error handler before calling CloudZoom.quickStart() e.g:

$.fn.CloudZoom.defaults.errorCallback =
function(error){ alert(error.type); };

variableMagnification (from V3.0)booleanWhether to allow variable magnificationtrue
startMagnification (from V3.0)string|numberInitial magnification (multiplier of small image size, do not put quotes around numbers).
"auto" will choose best quality magnification based on large image size.
minMagnification (from V3.0)string|numberMinimum allowable magnification (multiplier of small image size).
"auto" will ensure lens size does not get larger than small image.
maxMagnification (from V3.0)string|numberMaximum allowable magnification (multiplier of small image size).
"auto" will choose best quality magnification based on large image size.
easing (from V3.0)numberHigher the number, the smoother/slower the easing of movement.8
lazyLoadZoom (from V3.0 rev 1302181432)booleanLazy load the zoom image. If true, zoom image will only be loaded after initial interaction with small image, otherwise will be loaded immediately on page load. Lazy loading can be useful if there are many zoom images that need to be loaded.false
mouseTriggerEvent (from V3.0 rev 1302271415)stringMouse event used to trigger zoom. Use either "mousemove" or "click".mousemove
disableZoom (from V3.0 rev 1303081245)string|booleanUse to disable zoom. false = no disable, true = disable always, "auto" = disable only if zoom image is the same size or smaller than small image. Note, if you have set magnification levels larger than 1, zoom will not be disabled.false
disableOnScreenWidth (from V3.1 rev 1404081640)numberUse to disable zoom if page size less than or equal to specified value. Useful for disabling zoom on small mobile devices. Gallery elements will still function and change the image.0
(from 3.0 rev 1304181330)
booleanTurns gallery fade effect on or off. If you are using mouseover for changing gallery images, false is recommended.true
galleryHoverDelay (from 3.0 rev 1304251647)numberNumber of milliseconds to delay changing of images when using galleryEvent:'mouseover'. Stops flooding browser with image load requests. 200
(from 3.0 rev 1308161049)
booleanIf true, zoom window will remain open when mouse moves out of small image. false
(from 3.0 rev 1311041015)
numberSpecifies zoom window size (lens size adjusted). Overrides any CSS size. 0
(from 3.0 rev 1311041015)
numberSpecifies lens size (zoom window size adjusted). Overrides any CSS size. 0
hoverIntentDelay (from 3.1 rev 1311181400)numberSpecifies the amount of time (milliseconds) that user must mouse-hover to trigger zoom. A good value is 500. 0
hoverIntentDistance (from 3.1 rev 1311181400, DEPRECATED 3.1 rev 1507231015)numberSpecifies the distance moved in pixels that would be classed as slow. 2
autoInside (from 3.1 rev 1311191400)numberIf the page size becomes less than or equal to the specified width (pixels) Cloud Zoom will work in 'inside' mode. Useful for responsive pages, see here for a responsive Cloud Zoom example. 0
from 3.1 rev 1405291330
number|boolean Allow normal page touch-scrolling to work when images take up full device width.

Prior to version 3.1 rev 1410150700: Delay in milliseconds that touch needs to be held down before zoom opens (100 or less recommended).

After 3.1 rev 1410150700: Boolean, true or false to enable the feature.