Panning and Zooming Any Elements - panzoom

Panning and Zooming Any Elements - panzoom
File Size: 44.6 KB
Views Total:
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

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
});

7. Full plugin options with default values.

// Whether or not to transition the scale
animate: 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,

// 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

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
panzoom.zoomWithWheel(event, OPTIONS);

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.0.3 (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.