Panning and Zooming Any Elements - panzoom

File Size: 37.7 KB
Views Total: 99068
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
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 & 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.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.