It's easy to zoom images on your site

Getting started

If you use one of these platforms, click your platform and follow the instructions:

If you're not using one of the platforms above, install Magic Zoom Plus like so:

  1. Download Magic Zoom Plus trial.
  2. Unzip the file on your computer and FTP the magiczoomplus folder to your website directory (on your server), keeping the file and folder structure intact.
  3. Reference magiczoomplus.js and magiczoomplus.css files before the </head> of your page:

    <link type="text/css" rel="stylesheet" href="magiczoomplus/magiczoomplus.css"/>
    <script type="text/javascript" src="magiczoomplus/magiczoomplus.js"></script>
    

    If you cannot access the head section of your page, reference the files elsewhere such as the main content of your page.

  4. Link your small image to your large image with a class of MagicZoom:
    <a href="large-image.jpg" class="MagicZoom"><img src="small-image.jpg"></a>
  5. You've done it! Get inspiration from these examples or use the wizard to choose your perfect settings.

To remove the Magic Zoom Plus™ trial version message, buy a license then overwrite the magiczoomplus.js file with your licensed version.

Now let's look at how to customize Magic Zoom Plus...

Zoom size

The zoomed area is automatically set at the same dimensions as the small image, for example:

<a href="large.jpg" class="MagicZoom"><img src="small.jpg"></a>

Change the size of the zoomed area by specifying the zoomWidth and/or zoomHeight parameters. Notice that the location of the zoom window automatically changes if there is insufficient space on the users screen.

Here is a larger zoom window:

<a href="large.jpg" class="MagicZoom" data-options="zoomWidth:400px; zoomHeight:400px"><img src="small.jpg"></a>

The zoomed area size can also be set as a percentage of the small image:

<a href="large.jpg" class="MagicZoom" data-options="zoomWidth:70%; zoomHeight:100%"><img src="small.jpg"></a>

Zoom position

Define the location of the zoom window with zoomPosition setting. Try these examples for right, bottom, left, top (note that the position automatically changes to opposite side or to internal zoom if there is insufficient screen space):

<a href="large.jpg" class="MagicZoom" data-options="zoomPosition: top; expand: false;"><img src="small.jpg"></a>

Internal zoom

Zoom inside the image by setting the zoomPosition parameter to inner value.

<a href="large.jpg" class="MagicZoom" data-options="zoomPosition: inner"><img src="small.jpg"></a>

Placeholder

You can position the zoomed image literally anywhere on your page if you create a placeholder (e.g. <div id="zoom-placeholder">) and reference it with an unique #id in zoomPosition setting.

<a href="large.jpg" class="MagicZoom" data-options="zoomPosition: #zoom-placeholder;"><img src="small.jpg"></a>

<style>
  #zoom-placeholder {
    position: fixed;
    bottom: 25px;
    left: 10px;
    z-index: 100;
    width: 250px;
    height: 250px;
  }
</style>
<div id="zoom-placeholder"></div>

Distance

Change the distance from the main image to the zoom (default is 15px) with the zoomDistance parameter. Example:

<a href="large.jpg" class="MagicZoom" data-options="zoomDistance: 150"><img src="small.jpg"></a>

Zoom mode

Magic Zoom Plus offers 3 ways to zoom images: Zoom, Magnifier and Preview.

Zoom

By default, it will zoom on hover. Your code will look like this:

<a href="large.jpg" class="MagicZoom"><img src="small.jpg"></a>

Magnifier

To use the elegant magnifying glass effect set the zoomMode parameter as magnifier. The default size is 70% of the image. If you prefer magnifier as a square, add mz-square to the cssClass setting:

<a href="large.jpg" class="MagicZoom" data-options="zoomMode: magnifier"><img src="small.jpg"></a>

To control the magnifier width with your mousewheel, also add variableZoom parameter as true. Example:

<a href="large.jpg" class="MagicZoom" data-options="zoomMode: magnifier; variableZoom: true"><img src="small.jpg"></a>

Preview

You can show the entire large image on hover instead of part of the image. This is an excellent way to immediately show more detail for small images, such as on search results pages or category pages on an e-commerce site.

<a href="large.jpg" class="MagicZoom" data-options="zoomMode: preview; expand: false;"><img src="small.jpg"></a>

Turn off the zoom effect so that image only enlarge to full-screen. Set the zoomMode option to off:

<a href="large.jpg" class="MagicZoom" data-options="zoomMode: false"><img src="small.jpg"></a>

Gallery

You can combine multiple images into a gallery by adding an id attribute to the main image link and a data-zoom-id attribute to the alternative image links.

Use href attribute of the alternative image link to specify an URL to the zoom image and data-image for the path to the small image.

<a href="jeans1-big.jpg" class="MagicZoom" id="jeans"><img src="jeans1-small.jpg"></a>

<a data-zoom-id="jeans" href="jeans1-big.jpg" data-image="jeans1-small.jpg"><img src="jeans1-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans2-big.jpg" data-image="jeans2-small.jpg"><img src="jeans2-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans3-big.jpg" data-image="jeans3-small.jpg"><img src="jeans3-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans4-big.jpg" data-image="jeans4-small.jpg"><img src="jeans4-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans5-big.jpg" data-image="jeans5-small.jpg"><img src="jeans5-tiny.jpg"></a>

By default images swap with a dissolve transition when clicked. You can switch the images on mouse over with selectorTrigger: hover. To turn off a dissolve effect, set the transitionEffect to false:

<a href="jeans1-big.jpg" class="MagicZoom" id="jeans" data-options="selectorTrigger: hover; transitionEffect: false;"><img src="jeans1-small.jpg"></a>

<a data-zoom-id="jeans" href="jeans1-big.jpg" data-image="jeans1-small.jpg"><img src="jeans1-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans2-big.jpg" data-image="jeans2-small.jpg"><img src="jeans2-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans3-big.jpg" data-image="jeans3-small.jpg"><img src="jeans3-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans4-big.jpg" data-image="jeans4-small.jpg"><img src="jeans4-tiny.jpg"></a>
<a data-zoom-id="jeans" href="jeans5-big.jpg" data-image="jeans5-small.jpg"><img src="jeans5-tiny.jpg"></a>

Expanded view

Expanded view displays the enlarged image in a distraction free mode. Click on image to open an expanded view:

<a href="large.jpg" class="MagicZoom" data-options="expand: window"><img src="small.jpg"></a>

You can navigate through image gallery in the expanded view with arrows, and keys on keyboard or swipe gestures on touch screens.

Use × icon or Esc key to close the expanded view. You can also close the expanded view by clicking anywhere outside the large image. Should you wish to disable this option, simply set closeOnClickOutside to false:

<a href="large.jpg" class="MagicZoom" data-options="closeOnClickOutside: false"><img src="small.jpg"></a>

Full screen

By default the expanded view is set to window mode. This means it is stretched to the full size of the browser window. To show expanded view in the full-screen mode use expand: fullscreen option.

<a href="large.jpg" class="MagicZoom" data-options="expand: fullscreen"><img src="small.jpg"></a>

Zoom and pan

If the large image is bigger than the viewport, it will be scaled down. The user can zoom and pan image by clicking on it. Alternatively, you can configure Magic Zoom Plus to zoom in image automatically with the expandZoomOn: always parameter:

<a href="large.jpg" class="MagicZoom" data-options="expandZoomOn: click"><img src="small.jpg"></a>

By default the whole image is zoomed (expandZoomMode option is set to zoom). To allow visitors to magnify a portion of the image around mouse pointer with a loupe, use expandZoomMode: magnifier.

You can disable image magnification in the expanded view with the expandZoomMode: off:

<a href="large.jpg" class="MagicZoom" data-options="expandZoomMode: zoom"><img src="small.jpg"></a>

Background

Magic Zoom Plus displays a blurred background in the expanded view. If you prefer a plain background, you can set cssClass parameter to dark-bg for the translucent dark background, or use white-bg for the opaque white background:

<a href="large.jpg" class="MagicZoom" data-options=""><img src="small.jpg"></a>

Thumbnails

If images combined into a gallery, the thumbnails are displayed underneath the image in the expanded view. To remove thumbnails, simply put no-expand-thumbnails into the cssClass parameter:

<a href="large.jpg" class="MagicZoom" data-options="cssClass: no-expand-thumbnails"><img src="small.jpg"></a>

Hint

A hint is displayed on the image to indicate that the image is zoomable and can be controlled with the hint option.

By default the hint appears once and hides after the first interaction with the image. You can configure hint to always appear on the image with hint: always. To remove hint, set hint parameter to off:

<a class="MagicZoom" href="large.jpg" data-options="hint: once">
    <img src="small.jpg">
</a>

The text of the hint can be changed with the textHoverZoomHint option if zoom activates on hover or textClickZoomHint if zoom activates on click:

<a class="MagicZoom" href="large.jpg" data-options="expand: off; hint: always; textHoverZoomHint: Roll over image to zoom in; textClickZoomHint: Click image to zoom in"><img src="small.jpg"></a>

If you would like to change the hint text for the expanded view, you can do this using the textExpandHint property:

<a class="MagicZoom" href="large.jpg" data-options="zoomMode: off; textExpandHint: Click to open expanded view">
    <img src="small.jpg">
</a>

Caption

Add a caption to the image by using title attribute in the <a> tag:

<a class="MagicZoom" title="This is a dummy caption" href="large.jpg"><img src="small.jpg"></a>

By default the caption appears only in the expanded view. To show caption on the zoomed image, set zoomCaption parameter to top or bottom position:

<a class="MagicZoom" data-options="zoomCaption: top" href="large.jpg" ><img src="small.jpg"></a>

You can link the caption text in the expanded view to another page using the data-link attribute:

<a href="large.jpg" class="MagicZoom" title="Caption text can link to any URL" data-link="#caption-with-link">
    <img src="small.jpg">
</a>

If you want the caption not to appear in the expanded view set expandCaption: false.

Click to zoom

If you do not want to zoom image immediately on hover, you can configure Magic Zoom Plus to activate zoom on click:

<a href="large.jpg" class="MagicZoom" data-options="zoomOn: click"><img src="small.jpg"></a>

Lazy zoom

For the best user experience Magic Zoom Plus preloads the large image. However, you can configure it to load large image on demand (lazy-loading) with lazyZoom: true option. This means the large image will be loaded when the user triggers zoom or opens expanded view:

<a href="large.jpg" class="MagicZoom" data-options="lazyZoom: true"><img src="small.jpg"></a>

Autostart

Magic Zoom Plus starts automatically when page is loaded by default. To start it manually set autostart parameter to false:

<a href="large.jpg" class="MagicZoom" data-options="autostart: false"><img src="small.jpg"></a>

Retina images

Optimize your images for Retina / High DPI displays with 2x images. Add data-zoom-image-2x attribute to the <a class="MagicZoom"> tag for a high-resolution large image and data-image-2x attribute for a small HD image:

<a href="large.jpg" data-zoom-image-2x="large@2x.jpg" data-image-2x="small@2x.jpg" class="MagicZoom">
    <img src="small.jpg">
</a>

Styling

Control the look and feel of your images by using CSS.

Zoom window

Use the following CSS classes in your stylesheets to customize zoom window shape; border; background + more:

.mz-zoom-window {
  /* Applies in the default zoom mode */
}

.mz-zoom-window.mz-magnifier {
  /* Applies in the magnifier mode */
}

.mz-zoom-window.mz-preview {
  /* Applies in the preview mode */
}

.mz-zoom-window.mz-inner {
  /* Applies in internal zoom */
}

Lens

Alter the look of the lens over the image in the zoom mode with .mz-lens class:

.mz-lens {
  /* Applies to the lens over the image */
}

Caption

Control the styles of the caption with these CSS:

.mz-zoom-window .mz-caption {
  /* Applies to the caption in zoom window */
}

.mz-expand .mz-caption {
  /* Applies to the caption in expanded view */
}

Gallery

Customize look & feel of the thumbnails in a gallery using the CSS below:

.mz-thumb {
  /* Applies to every thumbnail */
}

.mz-thumb-selected {
  /* Applies to the active thumbnail */
}

You can either add the style to one of your external CSS files or you can place it directly into the HTML of your page.

If placing the style in your HTML page, use <style> tags, for example:

<style>
.mz-thumb {
  border: 1px;
}
.mz-thumb-selected {
  filter: brightness(100%);
}
</style>

The style can go anywhere in your HTML page after the magiczoom.css file.

API & callbacks

API methods

You can use the Magic Zoom Plus API commands to control your images dynamically:

  • MagicZoom.start(node) - Start Magic Zoom Plus instance by #id or reference to <a> tag. Without parameters, start all instances on the page.
  • MagicZoom.stop(node) - Stop Magic Zoom Plus instance by #id or reference to <a> tag. Without parameters, stop all instances on the page.
  • MagicZoom.refresh(node) - Reload Magic Zoom Plus instance by #id or reference to <a>. Without parameters, reload all instances on the page.
  • MagicZoom.update(node, large-image-url, small-image-url) - Update particular zoom by #id.
  • MagicZoom.prev(node) - Go to the previous image of a particular zoom.
  • MagicZoom.next(node) - Go to the next image of a particular zoom.
  • MagicZoom.switchTo(node, selector) - Switch to a particular image by selector. selector - is either reference to selector's DOM element or index number of the selector (index number starts from 0).
  • MagicZoom.zoomIn(node) - Activate zoom mode on a particular zoom.
  • MagicZoom.zoomOut(node) - Deactivate zoom mode on a particular zoom.
  • MagicZoom.expand(node) - Open expanded view of a particular zoom.
  • MagicZoom.close(node) - Close expanded view of a particular zoom.

There are all sorts of uses. Here are a few:

Callbacks

  • onZoomReady: function(zoom_id){ } - Fires when zoom instance is ready to operate.
  • onUpdate: function(zoom_id, previous_image_selector, new_image_selector){ } - Fires when images swapped.
  • onZoomIn: function(zoom_id){ } - Fires when zoom mode activated.
  • onZoomOut: function(zoom_id){ } - Fires when zoom mode deactivated.
  • onExpandOpen: function(zoom_id){ } - Fires when expanded view opened.
  • onExpandClose: function(zoom_id){ } - Fires when expanded view closed.

Parameters

Configure Magic Zoom Plus for your needs with the parameters listed below. Apply parameters via the data-options attribute, with multiple parameters separated by a semi-colon, for example:

<a href="large.jpg" class="MagicZoom" data-options="expand:fullscreen; rightClick:true;"><img src="small.jpg"></a>

Or parameters can be set globally with the mzOptions variable, e.g.:

<script>
var mzOptions = {
    expand: 'fullscreen',
    rightClick: 'true'
};
</script>
Parameters for Magic Zoom Plus
ParameterDefaultOptionsDescription
zoomModezoomzoom | magnifier | preview | offHow to zoom image
zoomOnhoverhover | clickWhen activate zoom
zoomPositionrightleft | right | top | bottom | innerPosition of zoom window
zoomWidthauto<percentage> | <pixels> | autoWidth of zoom window
zoomHeightauto<percentage> | <pixels> | autoHeight of zoom window
zoomDistance15<pixels>Distance from small image to zoom window
zoomCaptionofftop | bottom | offPosition of caption on zoomed image
hintonceonce | always | offHow to show hint
variableZoomfalsetrue | falseWhether to allow changing zoom ratio with mouse wheel
smoothingtruetrue | falseEnable/disable smooth zoom movement
expandwindowwindow | fullscreen | offHow to show expanded view
expandZoomModezoomzoom | magnifier | offHow to zoom image in expanded view
expandZoomOnclickclick | alwaysWhen and how activate zoom in expanded view. 'always' - zoom automatically activates upon entering the expanded view and remains active.
expandCaptiontruetrue | falseWhether to show caption in expanded view
closeOnClickOutsidetruetrue | falseWhether to close expanded view on click outside the image
lazyZoomfalsetrue | falseWhether to load large image on demand (on first activation)
rightClickfalsetrue | falseWhether to allow context menu on right click
upscaletruetrue | falseWhether to scale up the large image if its original size is not enough for a zoom effect
selectorTriggerclickclick | hoverMouse event used to swtich between multiple images
transitionEffecttruetrue | falseWhether to enable dissolve effect when switching between images
autostarttruetrue | falseWhether to start Zoom on image automatically on page load or manually
cssClass stringExtra CSS class(es) to apply to zoom instance
textHoverZoomHintHover to zoomstringHint that shows when zoom mode is enabled, but inactive. Zoom activates on hover (zoomOn: hover)
textClickZoomHintClick to zoomstringHint that shows when zoom mode is enabled, but inactive. Zoom activates on click (zoomOn: click)
textExpandHintClick to expandstringHint that shows when zoom mode activated, or in inactive state if zoom mode is disabled
textBtnCloseClosestringText label that appears on mouse over the "close" button in expanded view
textBtnPrevPreviousstringText label that appears on mouse over the "previous" button arrow in expanded view
textBtnNextNextstringText label that appears on mouse over the "next" button arrow in expanded view

Options for mobile devices

For mobile devices (smartphones in particular), global parameters can be overwritten with the mzMobileOptions variable:

<script>
var mzMobileOptions = {
  zoomMode: 'magnifier'
};
</script>

or locally via the data-mobile-options attribute:

<a class="MagicZoom" data-mobile-options="zoomMode: magnifier;">
Parameters for Magic Zoom Plus
ParameterDefaultOptionsDescription
zoomModezoomzoom | magnifier | offHow to zoom image
textHoverZoomHintTouch to zoomstringHint that shows when zoom mode is enabled, but inactive. Zoom activates on hover (zoomOn: hover)
textClickZoomHintDouble tap to zoomstringHint that shows when zoom mode is enabled, but inactive. Zoom activates on click (zoomOn: click)
textExpandHintTap to expandstringHint that shows when zoom mode activated, or in inactive state if zoom mode is disabled