Panning and Zooming Any Elements - panzoom

panzoom is a simple jQuery & Vanilla JavaScript plugin that allows you to drag, pan, zoom in/out any elements of your webpage using CSS3 transforms. Fast, performant and mobile-friendly.

It supports panning and zooming images, text, videos, divs and many other html elements.

Currently works as a Vanilla JavaScript, but can still integrate as a jQuery plugin. You can also download the jQuery Version (3.x) here.

Table Of Contents:

• Installation
• Usage
• Options
• API Methods
• Event Handlers

Installation & Download:

# Yarn
$ yarn add @panzoom/panzoom

# NPM
$ npm install @panzoom/panzoom --save

Basic Usage:

1. Import the panzoom after installation.

import Panzoom from '@panzoom/panzoom'

2. Or directly include the panzoom.js in the document.

<!-- From Local -->
<script src="/path/to/dist/panzoom.min.js"></script>
<!-- From A CDN -->
<script src="https://cdn.jsdelivr.net/npm/@panzoom/panzoom/dist/panzoom.min.js"></script>
<!-- Or -->
<script src="https://www.unpkg.com/@panzoom/panzoom/dist/panzoom.js"></script>

3. Create an html element you want to apply the panning and zooming functionality on.

<div id="panzoom"> 
  <img src="1.svg" width="900" height="900"> 
</div>

5. Create the zoom in/out control buttons (OPTIONAL). To learn how to enable the controls, see the API methods as shown below.

<button id="zoom-in">Zoom In</button>
<button class="zoom-out">Zoom Out</button>
<input type="range" class="zoom-range">
<button class="reset">Reset</button>

6. Attach the plugin to the element and done.

const element = document.getElementById('panzoom')
const panzoom = Panzoom(element, {
      // options here
});

// enable mouse wheel
const parent = element.parentElement
parent.addEventListener('wheel', panzoom.zoomWithWheel);

7. Full plugin options with default values.

// Whether or not to transition the scale
animate: false,

// This option treats the Panzoom element's parent as a canvas. 
// Effectively, Panzoom binds the down handler to the parent instead of the Panzoom element, so that pointer events anywhere on the "canvas" moves its children. 
canvas: false,

// Default cursor style for the element
cursor: 'move',

// Disable panning and zooming
disablePan: false,
disableZoom: false,

// Pan only on the X or Y axes
disableXAxis: false,
disableYAxis: false,

// Animation duration (ms)
duration: 200,

// CSS easing used for scale transition
easing: 'ease-in-out',

// An array of elements to exclude
exclude: [],

// Or add the CSS class to element that should be excluded
excludeClass: 'panzoom-exclude',

// Override the default handle start event here
handleStartEvent: function (e) {
  e.preventDefault();
  e.stopPropagation();
},

// min/max scale factors
maxScale: 4,
minScale: 0.125,

// CSS overflow property
overflow: 'hidden',

// Disable panning while the scale is equal to the starting value
panOnlyWhenZoomed: false,

// Enable panning during pinch zoom
pinchAndPan: false,

// When passing x and y values to .pan(), treat the values as relative to their current values
relative: false,

// Override the transform setter. 
setTransform: setTransform,

// X Value used to set the beginning transform
startX: 0,

// Y Value used to set the beginning transform
startY: 0,

// Scale used to set the beginning transform
startScale: 1,

// Step options
step: 0.3,

// Contain the panzoom element either inside or outside the parent.
// "inside" | "outside"
contain: null,

// set touch-action on both the Panzoom element and its parent
touchAction: 'none'

8. API methods.

// destroy the instance
panzoom.destroy();

// get options
panzoom.getOptions();

// get the current x/y translation
panzoom.getPan();

// get the current scale
panzoom.getScale();

// pan the Panzoom element to given x and y coordinates
panzoom.pan(x, y, OPTIONS);

// reset the Panzoom element
panzoom.reset(OPTIONS);

// set/update options
panzoom.setOptions(OPTIONS);

// set styles
panzoom.setStyle(name, value);

// zoom the Panzoom element to a given scale
panzoom.zoom(scale, OPTIONS);

// zoom in the Panzoom element
panzoom.zoomIn(OPTIONS);

// zoom out the Panzoom element
panzoom.zoomOut(OPTIONS);

// zoom the Panzoom element to a focal point using the given pointer/touch/mouse event or constructed point.
panzoom.zoomToPoint(point, pointerEvent, OPTIONS);

// zoom with mouse wheel
// Bind the default down, move, and up event listeners to the Panzoom element. 
// This does not normally need to be called. 
// It gets called by default when creating a new Panzoom object, but can be skipped with the noBind option.
panzoom.bind();

9. Event handlers.

// The event object passed as an argument to the listener will always have a detail property with the current x, y, and scale values.
// Events can be silenced when the silent option is set to true, either globally or when passed to pan, any zoom method, or reset.
// Avoid putting too much logic in these event handlers as it could effect the performance of panning or zooming.

element.addEventListener('panzoomstart', (event) => {
  // do something
});

element.addEventListener('panzoomchange', (event) => {
  // do something
});

element.addEventListener('panzoomzoom', (event) => {
  // do something
});

element.addEventListener('panzoompan', (event) => {
  // do something
});

element.addEventListener('panzoomend', (event) => {
  // do something
});

element.addEventListener('panzoomreset', (event) => {
  // do something
});

Changelog:

v4.6.0 (2025-01-16)

• support attached shadow dom elements

v4.5.1 (2022-09-07)

• bugfixes

v4.5.0 (2022-05-28)

• add pinchAndPan option to enable panning during pinch zoom
• panzoom: expose the pointer event handlers
• Bug Fixes

v4.4.4 (2022-02-01)

• Bug Fixes

v4.4.3 (2021-10-30)

• Bug Fixes: pan: avoid triggering the pan event if no change

v4.4.2 (2021-10-21)

• Bug Fixes

v4.4.1 (2021-06-12)

• Bug Fixes

v4.4.0 (2021-05-06)

• events: add originalEvent to custom events detail
• resetstyle: add resetStyle method for removing all panzoom styles

v4.3.2 (2020-09-09)

• Bug Fixes

v4.3.1 (2020-07-22)

• check for window and document to allow ssr loading

v4.3.0 (2020-07-21)

• add bind method and noBind option
• demo updated
• doc updated

v4.2.0 (2020-07-08)

• events: expose event names used in the current browser
• options: add touchAction option for setting the touch-action style

v4.1.0 (2020-04-07)

• add option for moving the child via the parent

v4.0.4 (2020-03-28)

• Bug Fixes

v4.0.3 (2020-01-29)

• Bug Fixes

v4.0.2 (2020-01-16)

• Fixed zoomtopoint: should be able to override animate

v4.0.1 (2020-01-13)

• Fixed reset: ignore disable and panOnlyWhenZoomed options
• Fixed setoptions: bind/destroy depending on disablePan option

v4.0.0 (2019-12-17)

• Rewritten in Vanilla JavaScript, but can still integrate as a jQuery plugin.

v3.2.3 (2019-05-09)

• Fixes compatibility with jQuery 3.4+

2017-06-22

• allow panzoom to work on rotated/transformed images

v3.2.2 (2016-08-29)

• [zoom] remove exponential option; add linear option

v3.2.1 (2016-08-13)

• update

v3.2.0 (2016-07-27)

• SVG: use CSS transitions on SVG elements wherever supported
• [Pointer events] add back support for pointer events

v3.1.1 (2016-07-20)

• update.

v2.0.6 (2016-02-02)

• update.

v2.0.5 (2014-04-03)

• update.

v2.0.4 (2014-04-03)

• update.

v2.0.3 (2014-03-28)

• Get offset every time when zooming unless parentOffset is set specifically

v2.0.2 (2014-03-28)

• update.

v1.12.6 (2014-03-27)

• update.

v1.12.5 (2014-03-25)

• update.

v1.12.4 (2014-03-14)

• update.

v1.12.3 (2014-03-13)

• update.

v1.12.2 (2014-03-12)

• update.

v1.12.1 (2014-03-05)

• update.

v1.12.0 (2014-03-04)

• update.

v1.11.2 (2014-02-28)

• update.

v1.11.0 (2014-02-27)

• Document static properties.
• Add pointerEvent test results to the Panzoom object for convenience.

v1.9.1 (2014-01-28)

• version update.

v1.9.0 (2014-01-24)

• version update.

v1.8.6 (2014-01-14)

• version update.

v1.7.0 (2013-10-16)

• Pass through all original properties from the closing click or touch event to the panzoomend event.

v1.7.0 (2013-10-16)

• Support CommonJS syntax

v1.6.8 (2013-09-15)

• Move default step for range inputs to an option. Give input attribute precendence over default, but explicit option precendence over attribute.

v1.6.7 (2013-09-06)

• Add mousewheel plugin to fix demo across browsers. 
• Account for auto marginRight when text-align is not center on the panzoom element's parent.

v1.6.7 (2013-09-06)

• Add mousewheel plugin to fix demo across browsers. 
• Account for auto marginRight when text-align is not center on the panzoom element's parent.

v1.6.5 (2013-08-23)

• Stick to attributes for SVG to avoid conflicts with style
• Demos and docs updates for focal point zooming

v1.6.1 (2013-08-17)

• Fix an issue with how the increment is used in .zoom()

v1.5.0 (2013-08-15)

• Update demo and homepage for focal point zooming

v1.4.2 (2013-08-13)

• Release minor patch v1.4.2

v1.4.1 (2013-08-13)

• Fix inverted contianment for when the panzoom element is larger than its container.

 

---

This awesome jQuery plugin is developed by timmywil. For more Advanced Usages, please check the demo page or visit the official website.