Magic Zoom™ integration

Simply follow the Instructions below to install Magic Zoom™ in just 5 minutes, then you can customize it as you wish.

1. Installation

If you're using one of these platforms, click your platform and follow the instructions to install the Magic Zoom™ module:

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

  1. Download the Magic Zoom™ demo (or download a module listed to the right if you use such a platform).
  2. Upload magiczoom folder to your website.
  3. Reference the CSS and JS files before the </head> of your page. Example:

    <link type="text/css" rel="stylesheet" href="magiczoom/magiczoom.css"/>

    <script type="text/javascript" src="magiczoom/magiczoom.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. Create a zoom by linking your small image to your big image with a CSS class of MagicZoom. Example:

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

  5. Buy Magic Zoom™ and upload your licensed magiczoom.js file to remove the "please upgrade" message. Or, apply for a free license if your site is non-commercial.

Your HTML should look something like this:



<title>Magic Zoom example</title>

<link rel="stylesheet" href="magiczoom/magiczoom.css" type="text/css" />

<script src="magiczoom/magiczoom.js" type="text/javascript"></script>



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



Now it's working, use the wizard to choose your perfect settings. If you get stuck, email us.

This 4-minute video summarises the setup process:

Below, we explain all the Magic Zoom™ options and how to adjust them, starting with Size...

2. Size

Change the size of the zoomed area with zoom-width and/or zoom-height parameters. The default size is 300px by 300px. Here is a smaller zoom window:

<a href="big.jpg" class="MagicZoom" rel="zoom-width:290px; zoom-height:152px"><img src="small.jpg"/></a>

Notice how the square area under the cursor automatically changes size when you change the dimensions of the zoomed area. Here is a larger zoom window:

<a href="big.jpg" class="MagicZoom" rel="zoom-width:400px; zoom-height:400px"><img src="small.jpg"/></a>

You can also set the size of the zoomed area as a percentage of the small image.

<a href="big.jpg" class="MagicZoom" rel="zoom-width:70%; zoom-height:100%"><img src="small.jpg"/></a>

3. Position

Adjust the location of the zoomed image with zoom-position. Try these examples for left, top, bottom, right (note that the position automatically moves to another position if there is insufficient screen space):

<a href="big.jpg" class="MagicZoom" rel="zoom-position: top"><img src="small.jpg"/></a>

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

<a href="big.jpg" class="MagicZoom" rel="zoom-distance:200"><img src="small.jpg"/></a>

You can position the zoomed image literally anywhere on your page if you give it a unique id and reference it with the div. Place your div anywhere in your code and position it with CSS. Example HTML:

<a href="big.jpg" class="MagicZoom" rel="zoom-position:#yourzoom"><img src="small.jpg"/></a>
<div id="yourzoom"></div>

Magic Zoom™ automatically changes the location if there is insufficient space on the users screen.

4. Internal zoom

Zoom inside the image by setting the zoom-position to inner. Example:

<a href="big.jpg" class="MagicZoom" rel="zoom-position: inner"><img src="small.jpg"/></a>

5. Multiple images

To display different images of a product and swap between them, add an id attribute to the main image link and a rel attribute to the alternative image links.

In this example, the unique id is bike. There are 3 image sizes - big, small and tiny.

<a href="1big.jpg" class="MagicZoom" id="bike"><img src="1small.jpg"></a>

<a href="1big.jpg" rel="zoom-id:bike" rev="1small.jpg"><img src="1tiny.jpg"/></a>
<a href="2big.jpg" rel="zoom-id:bike" rev="2small.jpg"><img src="2tiny.jpg"/></a>
<a href="3big.jpg" rel="zoom-id:bike" rev="3small.jpg"><img src="3tiny.jpg"/></a>

You can swap the images on hover with selectors-change. To prevent unintentional swapping, a short delay of 200 miliseconds is added. This can be adjusted with selectors-mouseover-delay:

<a href="1big.jpg" class="MagicZoom" id="bike" rel="selectors-change:mouseover; selectors-mouseover-delay:100"><img src="1small.jpg"></a>

4 different effects can be used to change images via selectors-effect. The default effect is dissolve (used in the example above). False will remove the effect so the images swap immediately.

Pounce will expand and contract the images:

<a href="1big.jpg" class="MagicZoom" id="bike" rel="selectors-effect:pounce"><img src="1small.jpg"></a>

Fade will brighten the image towards white and dissolve it at the same time:

<a href="1big.jpg" class="MagicZoom" id="bike" rel="selectors-effect:fade"><img src="1small.jpg"></a>

You can also adjust the speed of the effect with selectors-effect-speed (default is 400ms). For example:

<a href="1big.jpg" class="MagicZoom" id="bike" rel="selectors-effect-speed:800"><img src="1small.jpg"></a>

You can highlight the current thumbnail using CSS and add hover effects. In the example below, a class of Selector has been created:

<a href="1big.jpg" class="MagicZoom" id="bike" rel="selectors-class: Active"><img src="1small.jpg"></a>

<a href="1big.jpg" rel="zoom-id:bike" rev="1small.jpg" class="Selector"><img src="1tiny.jpg"/></a>
<a href="2big.jpg" rel="zoom-id:bike" rev="2small.jpg" class="Selector"><img src="2tiny.jpg"/></a>
<a href="3big.jpg" rel="zoom-id:bike" rev="3small.jpg" class="Selector"><img src="3tiny.jpg"/></a>

Defined in the CSS like so:

.Selector img {
border: 2px solid #E0DEB5;
.Selector.Active img {
border: 2px solid #777544;

Even more customizations are available. Place the images literally anywhere on your page. Use any number of images. Switch between the images via thumbnails or text or even a form object (e.g. dropdown or button). All sorts of setups are possible - contact us if you need any help.

6. Preload images

You can preload the images in advance (once all other page content has downloaded) or you can trigger them to download on demand (lazy loading).

By default, only the first large in a group of multiple images will download. The other large images will download when the user hovers over the image. This reduces the total file-size of your page because many of visitors won't look at those large images. Those that do look at those images must wait briefly while they download on demand.

If you prefer instant image loading, you can preload all large images like so:

<a href="big.jpg" class="MagicZoom" rel="preload-selectors-big:true"><img src="small.jpg"/></a>

7. Initialization

The large image is downloaded automatically on page load. To reduce your bandwidth usage, you can set the large image to download on click or on hover (lazy loading). The user experience is not as good because there is a delay before viewing the image, so this option is set to false by default. To download the large image on hover or click, use the initialize-on parameter like so:

<a href="big.jpg" class="MagicZoom" rel="initialize-on: mouseover;"><img src="small.jpg"/></a>

8. Alignment

Align the zoom to any edge of your main image. By default it aligns to the top right edge. To adjust it, change the zoom-align parameter to left, top, bottom or center. Example:

<a href="big.jpg" class="MagicZoom" rel="zoom-align: center"><img src="small.jpg"/></a>

9. Hint

A hint is displayed on the image to indicate that the image is zoomable. It can be text or an image or both. The hint can be removed like so:

<a href="big.jpg" class="MagicZoom" rel="hint: false"><img src="small.jpg"/></a>

The text can be changed with hint-text. Example:

<a href="big.jpg" class="MagicZoom" rel="hint-text: Any text you want!"><img src="small.jpg"/></a>

You can also use hint-text to remove the text and show the icon only:

<a href="big.jpg" class="MagicZoom" rel="hint-text:;"><img src="small.jpg"/></a>

To change the icon to a different image, open magiczoom.css and replace hint.gif with another image. Examples:

.MagicZoomHint {
background: url(graphics/icon-of-your-choice.gif);

You can move the hint to any corner (top left, top right, bottom left, bottom right) or centrally (top center, bottom center) with the hint-position parameter (tl / tr / tc / bl / br / bc). Example:

<a href="big.jpg" class="MagicZoom" rel="hint-position: br; hint-text: Awesome detail!; "><img src="small.jpg"/></a>

10. Title

Add a caption on your zoomed image by using the title attribute in the <a> tag. Example:

<a href="big.jpg" class="MagicZoom" title="Hey! This is a caption."><img src="small.jpg"/></a>

The caption can be turned off by setting show-title to false. Or it can be moved to the bottom, for example:

<a href="big.jpg" class="MagicZoom" rel="show-title:bottom" title="This caption is under the image."><img src="small.jpg"/></a>

Change the font, colours and borders via the magiczoom.css file. Example:

.MagicZoomHeader {
font-size: 16pt !important;
line-height: 150% !important;
color: #6B6526;
background: #E5DF9C;
text-align: center !important;

To hide the title, either delete it or set show-title to false.

<a href="big.jpg" class="MagicZoom" title="Hey! This is a caption." rel="show-title:false"><img src="small.jpg"/></a>

11. Loading message

While the large image is downloading, it says "Loading zoom...". You can change the text by using the loading-msg parameter. Example:

<a href="big.jpg" class="MagicZoom" rel="loading-msg:Put your message here!"><img src="small.jpg"/></a>

You can remove the loading message by setting show-loading to false.

<a href="big.jpg" class="MagicZoom" rel="show-loading:false"><img src="small.jpg"/></a>

This animated GIF shows to the left of the loading message. The file location is determined in magiczoom.css. You can replace it with your own GIF if you wish.

You can customise the loading box opacity (default is 75) and position (default is -1). For example:

<a href="big.jpg" class="MagicZoom" rel="loading-opacity:50; loading-position-x:150; loading-position-y:20"><img src="small.jpg"/></a>

12. Transparency

The opacity of the mouse hover can be changed from the default (50) to any value between 0 (transparent) and 100 (solid). Example:

<a href="big.jpg" class="MagicZoom" rel="opacity:77"><img src="small.jpg"/></a>

Alternatively, the mouse hover can stay clear and the opacity of the rest of the image can change. Example:

<a href="big.jpg" class="MagicZoom" rel="opacity-reverse:true"><img src="small.jpg"/></a>

13. Smoothing

Smoothing is an effect to gradually decelerate the zoom to a stop. You can change the speed (40 is default) to a value from 0 (slow) to 99 (fast). Example:

<a href="big.jpg" class="MagicZoom" rel="smoothing-speed:15"><img src="small.jpg"/></a>

You can turn it off like so:

<a href="big.jpg" class="MagicZoom" rel="smoothing:false"><img src="small.jpg"/></a>

14. Fade in/out

You can adjust the time taken to fade the zoom in/out (in milliseconds). For example:

<a href="big.jpg" class="MagicZoom" rel="zoom-fade-in-speed:1200; zoom-fade-out-speed:400"><img src="small.jpg"/></a>

You can also turn it off to make the zoom appear immediately:

<a href="big.jpg" class="MagicZoom" rel="zoom-fade:false"><img src="small.jpg"/></a>

15. Shadow / glow

A drop shadow shows behind the zoomed image. You can change this effect to a glow like so:

<a href="big.jpg" class="MagicZoom" rel="zoom-window-effect: glow"><img src="small.jpg"/></a>

You can remove the shadow like so:

<a href="big.jpg" class="MagicZoom" rel="zoom-window-effect: false"><img src="small.jpg"/></a>

16. Show entire image

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 ecommerce site. Example:

<a href="big.jpg" class="MagicZoom" rel="entire-image:true"><img src="small.jpg"/></a>

Try using a large image of about 300-450px.

17. Click to activate

If you don't want the image to zoom immediately on mouseover, you can set it to activate on click:

<a href="big.jpg" class="MagicZoom" rel="click-to-activate:true"><img src="small.jpg"/></a>

18. Click to deactivate

You can set the zoomed image to deactivate on click:

<a href="big.jpg" class="MagicZoom" rel="click-to-deactivate: true"><img src="small.jpg"/></a>

19. Borders & colors

To change borders, colors and backgrounds, edit the styles in magiczoom.css. For example, to remove the border around the zoomed image, change the CSS style to:

.MagicZoomBigImageCont {
border: none;

20. Hover area

Change the color and border of the mouse hover area (default is grey) by editing the MagicZoomPup syle. Example:

.MagicZoomPup {
border: 2px solid #C9A550;
background: #DBBE7A;
cursor: move;

21. Click and drag

The zoomed image can be shown on click/drag instead of on hover.

Turn it on like so:

<a href="big.jpg" class="MagicZoom" rel="drag-mode:true"><img src="small.jpg"/></a>

The zoom will move on drag or click. You can turn off the latter option like so:

<a href="big.jpg" class="MagicZoom" rel="drag-mode:true; move-on-click:false"><img src="small.jpg"/></a>

The initial position of the zoom can be changed (default is -1 which is centered). For example:

<a href="big.jpg" class="MagicZoom" rel="drag-mode:true; x:100; y:200"><img src="small.jpg"/></a>

In drag mode, the zoom window automatically becomes always visible. You can make it initially invisible like so:

<a href="big.jpg" class="MagicZoom" rel="drag-mode:true; always-show-zoom:false"><img src="small.jpg"/></a>

The position of Magic Zoom™ can be remembered. This can be a useful option in drag mode and also for multiple images. Example:

<a href="big.jpg" class="MagicZoom" rel="drag-mode:true; preserve-position:true"><img src="small.jpg"/></a>

22. Right click menu

The option to right click on an image is disabled by Magic Zoom™. You can enable right click like so:

<a href="big.jpg" class="MagicZoom" rel="right-click:true"><img src="small.jpg"/></a>

23. Frames per second

You can adjust the speed of the zoom in fps (frames per second). The default is 25 (same as television). The higher the fps, the smoother the zoom will feel as you move across the image. Low-performance computers might struggle to render the image if the fps is too high, so test your zoom if you increase the FPS. Example:

<a href="big.jpg" class="MagicZoom" rel="fps:40"><img src="small.jpg"/></a>

24. API

You can use the Magic Zoom™ API commands to change your images dynamincally (AJAX):

  • MagicZoom.start() - starts all zooms on the page.
  • MagicZoom.start(id) - starts a particular zoom by #id.
  • MagicZoom.stop() - stops all zooms on the page.
  • MagicZoom.stop(id) - stops a particular zoom by #id.
  • MagicZoom.zoomIn(id) - shows a particular zoom by #id.
  • MagicZoom.zoomOut(id) - hides a particular zoom by #id.
  • MagicZoom.refresh() - refreshes all zooms on the page.
  • MagicZoom.update(id) - updates a particular zoom by #id.

The update method accepts up to 4 parameters:

MagicZoom.update(id, big-image, small-image, extra-options)

If you just need to update the settings, leave big-image and small-image parameters blank.

You can trigger events once the zoom has started or updated by defining a function for the callback onready:

MagicZoom.options = {
  'onready': function(id, isUpdated) {
      alert('Zoom on <a id="'+id+'"> is ready');

Here are some of the many examples of how you could use the API:

For more examples, download the demo (zip) and open example13.html.

25. Z-index

If your zoomed image is hidden behind some other content on your page, you can bring the zoom to the front by setting the z-index in the magiczoom.css file. Open the file and add this class:

.MagicZoom {
z-index: 10002;

The value of 10002 can be changed to any value - whatever is high enough to move it in front of the item that is hiding the zoom.

26. Parameters

Over 40 parameters are listed below for customizing Magic Zoom™. Each parameter can be applied via the rel attribute, for example:

<a href="big.jpg" class="MagicZoom" rel="zoom-width: 400; hint:false; opacity:70; "><img src="small.jpg"/></a>

Or parameters may be set with the script tag and applied to every zoom on your page. If you use script, be sure to add commas after all variables, except the last one (or IE will give an error) and apostrophes around values like so:

<script type="text/javascript">
MagicZoom.options = {
'zoom-width': 400,
'hint': false,
'opacity': 70


Parameters for Magic Zoom™
Parameter Default Options Description
zoom-width 300 <pixels> or <percentage>
e.g. zoom-width: 400; or zoom-width: 100%;
Width of zoom window
zoom-height 300 <pixels> or <percentage>
e.g. zoom-height: 400; or zoom-height: 100%;
Height of zoom window
zoom-position right left / right / top / bottom / inner / #id Position of zoom window relative to small image
zoom-align top right / left / top / bottom / center Where to align zoom window against image
zoom-distance 15   Distance from small image to zoom window (px)
opacity 50 0-100 Opacity of hovered area
opacity-reverse false true / false Add opacity outside mouse box
smoothing true true / false Enable smooth zoom movement
smoothing-speed 40 1-99 Speed of smoothing
zoom-fade true true / false Zoom window fade effect
zoom-fade-in-speed 400   Zoom window fade-in speed (ms)
zoom-fade-out-speed 200   Zoom window fade-out speed (ms)
zoom-window-effect shadow shadow / glow / false Apply shadow or glow behind the zoom
fps 25   Frames per second for zoom effect
Multiple images
selectors-change click click / mouseover Method to switch between multiple images
selectors-mouseover-delay 200   Delay before switching thumbnails (ms)
selectors-effect dissolve dissolve / fade / pounce / false Dissolve, cross fade or pounce thumbnail when switching thumbnails
selectors-effect-speed 400   Speed of dissolve/fade effect (ms)
selectors-class   any name Define a CSS class of the active selector
preload-selectors-small true true / false Preload small images
preload-selectors-big false true / false Preload large images
zoom-id   id of main image Specify which images can be swapped
hint true true / false Display a hint to suggest that image is zoomable
hint-text Zoom    Show text in the hint
hint-position tl tl / tr / tc / bl / br / bc Position of the hint, top left, top right, etc.
hint-opacity 75 0-100 Opacity of the hint text/image
initialize-on load load / click / mouseover When to download large image
click-to-activate false true / false Click to show the zoom
click-to-deactivate false true / false Click to hide the zoom (this will also deactivate expand effect)
show-loading true true / false Loading message
loading-msg Loading zoom...   Loading message text
loading-opacity 75 0-100 Loading message opacity
loading-position-x -1   Loading message X-axis position, -1 is center
loading-position-y -1   Loading message Y-axis position, -1 is center
Zoom mode
disable-zoom false true/false Turn off the zoom effect
show-title top top / bottom / false Position of title on zoomed image (false = hidden)
title-source title title / #id Source of the title text
entire-image false true / false Show the entire large image on hover
fit-zoom-window true true / false Resize zoom window if big image is smaller than zoom window
drag-mode false true / false Click and drag to move the zoom
move-on-click true true / false Click to move the zoom (in drag mode)
preserve-position false true / false Remember position of zoom for multiple images and drag mode
x -1   Initial X-axis position for drag mode, -1 is center
y -1   Initial Y-axis position for drag mode, -1 is center
always-show-zoom false true / false Make zoom window always visible (automatically true in drag-mode)
right-click false true / original / expanded / false Show the browser menu on right-click