jQuery TileZoom Plugin

The jQuery TileZoom Plugin is an image zoom plugin which uses image tiles and provides a convenient way to zoom in and zoom out of high-resolution images.
See demo page with 2 examples: 2 Dollars (7356 x 3146) and Mona Lisa (2835 x 4289).

How it Works

The plugin provides a method called tilezoom which is invoked on a container element.
It’s simple html and javascript. Plugin doesn’t use canvas element, that is why it works with IE browsers too!

Tiles for the image should be generated with OpenZoom tile generator. You can use our TileGenerator (modified version of PHP Deep Zoom Tools) for this.
Then specify XML file path or path to tiles directory with width and height image resolution options. That’s all what you need.

How to use

Be sure to include the JQuery library. And just add this code inside your page head:

<link type="text/css" rel="stylesheet" media="all" href="tilezoom/jquery.tilezoom.css" />
<script type="text/javascript" src="tilezoom/jquery.tilezoom.js"></script>

Commands

The tilezoom function can be called in the following form:

$(document).ready(function(){
  $('#container').tilezoom('command');
});

The following command strings are supported:

'init'   // init tilezoom, default method
'destroy' // destroy tilezoom and unbinds all events
'zoom'  // zoom image to the specified level

Basic examples of usage:

$(document).ready(function(){
  $('#container').tilezoom({
    width: 2835,
    height: 4289,
    path: 'dest/mona_lisa_files',
    mousewheel: true
  });
});
$(document).ready(function(){
  $('#container').tilezoom({
    xml: 'dest/2dollars.xml',
    mousewheel: true
  });
});

Options

The following default options are provided by the plugin. They can be overridden by passing an options object to the tilezoom method.

var defaults = {
  width: null, // original image width in pixels. *(required) if no xml file
  height: null, // original image height in pixels *(required) if no xml file
  path: null, // tiles directory. *(required) if no xml file
  xml: null, // xml file with settings generated with Deep Zoom Tools
  tileSize: 254, // tile size in pixels
  overlap: 1, // tiles overlap
  thumb: 'thumb.jpg', // thumbnail filename
  format: 'jpg', // image format
  speed: 500, // animation speed (ms)
  easing: 'swing', // animation easing (jquery easing function name)
  mousewheel: false, // requires mousewheel event plugin: http://plugins.jquery.com/project/mousewheel
  gestures: false, // requires hammer.js event plugin, https://github.com/hammerjs/hammer.js
  zoomToCursor: true, // stay the same relative distance from the edge when zooming
  offset: '20%', //boundaries offset (px or %). If 0 image move side to side and up to down
  dragBoundaries: true, // If we should constrain the drag to the boundaries
  minZoomLevel: 0, // can't zoom out past level [minZoom]
  maxZoomLevel: 9999, // can't zoom in past level [maxZoom]
  wrapZoom: true, // If we're at the high level of resolution, go back to the start level
  beforeZoom: function($cont) {}, // callback before a zoom happens
  onZoom: function($cont, progress) {}, // callback for each zoom animation step
  afterZoom: function($cont) {}, // callback after zoom has completed
  callBefore: function($cont) {}, // this callback happens before dragging starts
  callAfter: function($cont, coords) {}, // this callback happens at end of drag after released "mouseup"
  initialized: function($cont) {}, // this callback happens after tilezoom  has been fully initalized.
  navigation: true, // navigation container ([true: show nav controls] or [false: don't show nav controls] or [DOM selector to insert controls in])
  zoomIn: null, // zoomIn button
  zoomOut: null, // zoomOut button
  goHome: null, // goHome button, reset to default state
  toggleFull: null // toggleFull button
}

Documentation

Here you can find more info about jQuery TileZoom Plugin.

Demos and Examples

Try

On this TileGenerator demo page you can try to upload your own image and see jQuery TileZoom Plugin in action.

Download

VersionDownloadsDate
jQuery TileZoom Plugin 1.2zip (21.82 KB)2015-December-02
jQuery TileZoom Plugin 1.1.1zip (21.66 KB)2014-February-04
jQuery TileZoom Plugin 1.1zip (21.62 KB)2012-October-11
TileZoom Exampleszip (36.73 MB)2011-December-12
TileGenerator 1.01zip (69.09 MB)2014-July-10
jQuery TileZoom Plugin 1.0zip (19.96 KB)2011-November-25
TileGenerator 1.0zip (69.46 MB)2011-December-12

Or you can download latest release on Github.

Changelog

jQuery TileZoom 1.2, 2015-December-02
———————–
Various modernization and flexibility enhancements ( Thanks to Michaël Fortin )
Most useful changes are:
– Mouse input is not disabled when a touchscreen is detected (mouse input didn’t work with Windows devices with seldom-used touchscreens).
– Using Hammer.js for more robust multi-touch input instead of dnaielglyde/TouchIt
– Added onZoom callback (called for each zoom step)
– Removed dependency on ES6 feature (yield, which didn’t bring much to the table anyway).

TileGenerator 1.01, 2014-July-10
———————–
– Fixed exif_read_data error.

jQuery TileZoom 1.1.1, 2014-February-04
———————–
– Added “initialized” callback which happens after tilezoom plugin has been fully initalized.

jQuery TileZoom 1.1, 2012-October-11
———————–
– Add touch gesture support (jQuery required dependency:
https://github.com/danielglyde/TouchIt). Supports pinch to zoom in and
out, double tapping to zoom and tap dragging
– Add a gestures property and sets to false (just like mousewheel).
– Add dragBoundaries boolean to optionally turn off constraining image
to boundaries while dragging
– Add double-click to zoom-in
– Fix unbind the mousemove on mouse up
– Add public resize() method if the container resizes
– Fix issue where certain mousewheels (or trackpads) were giving a
non-interger based delta were causing it to scale the holder to an
un-even level (images would fail)
– Add optimization to not re-zoom if we’re already at the correct level
– Add CSS support for default navigation always showing with gestures on
Thanks to Matt Moore for all of these issues fixed.
===
– Fix issue “position: fixed;” on some Android 2.x devices.
Thanks to ericente

  • gecko

    Hi Evgeny,
    I am using your tilezoom plugin and it works great. However for some reason mine will continue zooming even if there are no more tiles generated for that level. I have tiles generated for 5 levels of zoom. But when I click on the plus sign, it will zoom past the 5th level. Is there a way I can set the limit of how far you can zoom?

    Thanks!

  • Evgeny Matsakov

    Hi, there!
    This is possible now with “minZoomLevel” and “maxZoomLevel” options ( Thanks to https://github.com/fortinmike ).
    Best, Evgeny

  • gecko

    Great thanks!!

  • gecko

    Also have you thought of adding a view port navigator like openseadragon has?

  • Evgeny Matsakov

    Do you mean like this one: https://openseadragon.github.io/examples/ui-viewport-navigator/
    This was not required on previous projects, so I didn’t build it. But this great idea for improvement!