Press "Enter" to skip to content

A Library for Panning and Zooming Elements using CSS Transformations | Panzoom

Panzoom is a small (~3.7KB gzipped) library for adding pan and zoom functionality to an element. Instead of using absolute positioning or adjusting width and height, Panzoom uses CSS transforms to take advantage of hardware/GPU acceleration in the browser, which means the element can be anything: an image, video, iframe, canvas, text, or any Thing.

panzoom example, npm panzoom, javascript pan zoom image, svg pan zoom, html5 canvas pan zoom

Mobile support

iOS, Android, and Windows Mobile are supported.

Panzoom includes support for touch gestures and even supports pinch gestures to zoom in. It is well suited for both mobile and desktop browsers. Uses pointer events by default where supported.

SVG support

Panzoom supports moving and zooming SVG elements directly.

In IE11, CSS animations/transitions don’t work on SVG elements, at least for the transform style. They work in other browsers.

One can implement transitions manually in IE11 using the setTransform option and integrate a tween library for javascript animations (eg tween.js).

How to make use of it:

Installation & Download:

# Yarn
$ yarn add @panzoom/panzoom

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

1. Import the pan zoom after set up.

import Panzoom from '@panzoom/panzoom'

2. Or instantly include the panzoom.js within the doc.

<!-- 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 component you need to apply the panning and zooming functionality on.

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

4. Create the zoom in/out control buttons.

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

5. Attach the plugin to the component and finished.

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

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

6. Full plugin choices 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,

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

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

7. API strategies.

// 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();

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

Panning and Zooming Any Elements, Panzoom Plugin/Github


See Demo And Download

Official Website(timmywil): Click Here

This superior jQuery/javascript plugin is developed by timmywil. For extra Advanced Usages, please go to the official website.

Be First to Comment

    Leave a Reply

    Your email address will not be published.