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>
<html>

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

        <!-- Include jQuery. -->
        <script type="text/javascript" src="http://code.jquery.com/jquery-1.8.1.min.js"></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">
            CloudZoom.quickStart();
        </script>    
    </head>
    
    <body>
        <!-- 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'" />
    </body>

</html>

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"/>
</a>

Properties

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 Name	Type	Description	Default Value
zoomImage	string	Path to the zoom image. If no zoom image is specified, the small image (as specifed in the image element) will be used.	""
tintColor	string	Color to use for the tint effect	#fff
tintOpacity	number	Opacity of tint 0-1. If zero, no tint will be visible.	0.25
animationTime	number	Duration of the animation effects in milliseconds.	500
lensClass	string	CSS class to use for lens.	cloudzoom-lens
easeTime (DEPRECATED V3.0)	number	Number 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)	boolean	Automatically sizes the zoom image to match the page image.	false
zoomPosition	number \| string	Specifies 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`	3
zoomOffsetX	number	Allows you to fine tune horizontal position of zoom. From 3.0 rev 1303151613 also works in 'inside' mode	15
zoomOffsetY	number	Allows you to fine tune vertical position of zoom. From 3.0 rev 1303151613 also works in 'inside' mode	0
zoomFullSize DEPRECATED (see zoomSizeMode)	boolean	Zoom window appears at full size of zoom image.	false
zoomFlyOut	boolean	Turns 'flying' zoom animation on or off.	true
zoomClass	string	CSS class to use for zoom window.	cloudzoom-zoom
zoomInsideClass	string	CSS class to use for zoom window when "inside" has been used for `zoomPosition`.	cloudzoom-zoom-inside
zoomSizeMode	string	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	lens
captionSource	string	Specify 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
captionType	string	Specify caption type, either "attr" or "html".	attr
captionPosition	string	Position of caption, "top" or "bottom".	top
uriEscapeMethod	boolean \| string	Use 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
errorCallback	function	Specify 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); };` `CloudZoom.quickStart();`	function(error){}
variableMagnification (from V3.0)	boolean	Whether to allow variable magnification	true
startMagnification (from V3.0)	string\|number	Initial magnification (multiplier of small image size, do not put quotes around numbers). "auto" will choose best quality magnification based on large image size.	auto
minMagnification (from V3.0)	string\|number	Minimum allowable magnification (multiplier of small image size). "auto" will ensure lens size does not get larger than small image.	auto
maxMagnification (from V3.0)	string\|number	Maximum allowable magnification (multiplier of small image size). "auto" will choose best quality magnification based on large image size.	auto
easing (from V3.0)	number	Higher the number, the smoother/slower the easing of movement.	8
lazyLoadZoom (from V3.0 rev 1302181432)	boolean	Lazy 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)	string	Mouse event used to trigger zoom. Use either "mousemove" or "click".	mousemove
disableZoom (from V3.0 rev 1303081245)	string\|boolean	Use 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)	number	Use 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
galleryFade (from 3.0 rev 1304181330)	boolean	Turns 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)	number	Number of milliseconds to delay changing of images when using `galleryEvent:'mouseover'`. Stops flooding browser with image load requests.	200
permaZoom (from 3.0 rev 1308161049)	boolean	If true, zoom window will remain open when mouse moves out of small image.	false
zoomWidth zoomHeight (from 3.0 rev 1311041015)	number	Specifies zoom window size (lens size adjusted). Overrides any CSS size.	0
lensWidth lensHeight (from 3.0 rev 1311041015)	number	Specifies lens size (zoom window size adjusted). Overrides any CSS size.	0
hoverIntentDelay (from 3.1 rev 1311181400)	number	Specifies 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)	number	Specifies the distance moved in pixels that would be classed as slow.	2
autoInside (from 3.1 rev 1311191400)	number	If 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
touchStartDelay 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.	0