Panzoom

Examples

Panzoom is a small library (~3.7kb gzipped) to add panning and zooming functionality to an element. Rather than using absolute positioning or setting 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, a video, an iframe, a canvas, text, WHATEVER.

For common support questions, see the FAQ.

Browser support

Here is a list of currently supported browsers.

Mobile support

iOS, Android, and Windows Mobile are supported.

Panzoom includes support for touch gestures and even supports pinch gestures for zooming. It is perfectly suited for both mobile and desktop browsers. It uses pointer events by default wherever supported.

SVG support

Panzoom supports panning and zooming SVG elements directly.

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

One could implement transitions manually in IE11 using the setTransform option and integrating a tweening library for javascript animations (such as tween.js).

Installing

With npm:

$ npm install --save @panzoom/panzoom

With yarn:

$ yarn add @panzoom/panzoom

Panzoom uses UMD and can be loaded a lot of ways.

With ES6 imports:

import Panzoom from '@panzoom/panzoom'

With commonjs or browserify:

const Panzoom = require('@panzoom/panzoom')

With an AMD loader in an anonymous module:

define(['@panzoom/panzoom'], function (Panzoom) {
  const elem = document.getElementById('panzoom-element')
  Panzoom(elem)
})

With a script tag:

With a script tag from a CDN:

Usage

const elem = document.getElementById('panzoom-element')
const panzoom = Panzoom(elem, {
  maxScale: 5
})
panzoom.pan(10, 10)
panzoom.zoom(2, { animate: true })

// Panning and pinch zooming are bound automatically (unless disablePan is true).
// There are several available methods for zooming
// that can be bound on button clicks or mousewheel.
button.addEventListener('click', panzoom.zoomIn)
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)

FAQ

1. What is transform-origin and why is it added to the panzoom element?

• The transform-origin is the origin from which transforms are applied. Panzoom ensures the defaults are set to what it expects to calculate focal point zooming.
• HTML elements default to '50% 50%'.
• SVG elements default to '0 0'.

2. I am using Panzoom with an `` tag and it's not working. What's wrong?

Object elements can eat up events, making it so they never reach Panzoom. To fix this, disable pointer events (pointer-events: none) on the `` tag and call Panzoom using a wrapper.

3. My links aren't working! How do I enable an anchor within a panzoom element?

Add class options.excludeClass (default is "panzoom-exclude") to whatever element you want to be clickable. Panzoom will check for this class before handling the event. Alternatively, add a reference to the element to the exclude option, or call event.stopImmediatePropagation() in an event handler on the clickable element.

A note on the async nature of Panzoom

In some cases, setting one thing and then setting another synchronously will not work as intended.

For instance, the following usually works fine.

const panzoom = Panzoom(elem)
panzoom.zoom(2)
panzoom.pan(100, 100)

However, you might find that the things start breaking when the contain option is set.

This is due to the fact that in order for Panzoom to retrieve proper dimensions, the scale needs to be painted.

If you find that things aren't looking quite right, try the following instead...

panzoom.zoom(2)
setTimeout(() => panzoom.pan(100, 100))

4. I'm using Panzoom with SVG text elements and am seeing some weird text resizing. How do I fix this?

Add text-rendering="geometricPrecision" to your `