svg.panzoom.js

A plugin for svg.js that enables panzoom for svg elements

Getting started

npm install @svgdotjs/svg.js @svgdotjs/svg.panzoom.js

Include this plugin after including the svg.js library in your html document.

<script src="node_modules/@svgdotjs/svg.js/dist/svg.js"></script>
<script src="node_modules/@svgdotjs/svg.panzoom.js/dist/svg.panzoom.js"></script>

Or from a cdn:

<script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.js/dist/svg.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.panzoom.js/dist/svg.panzoom.js"></script>

A bundle is also attached to every release.

Or for esm just import it:

import { SVG } from '@svgdotjs/svg.js'
import '@svgdotjs/svg.panzoom.js'

To enable pan/zoom on an svg:

// enables panZoom
var canvas = SVG()
  .addTo('#id')
  .size(1000, 1000)
  .viewbox('0 0 1000 1000')
  .panZoom()

// zoom programatically
canvas.zoom(lvl, point)

You can configure panZoom by passing options to it.

• zoomMin: Minimal zoom level
• zoomMax: Maximal zoom level
• zoomFactor: How much is zoomed by one mouse wheel step

This could look like this:

var canvas = SVG()
  .addTo('#id')
  .size(1000, 1000)
  .viewbox('0 0 1000 1000')
  .panZoom({ zoomMin: 0.5, zoomMax: 20 })

Setting the min and max value will automatically restrict the zoom to the provided level.
However you are still able to change the zoom out of that bonds by calling zoom(lvl) programatically.

On touchable devices a pinchZoom gesture is supported. Min and max values also apply here.

Zooming is animatable, too:

canvas
  .zoom(1) // uses center of viewport by default
  .animate()
  .zoom(2, { x: 100, y: 100 }) // zoom into specified point

To disable panZoom or change its options just call it again with false or the new options.

Options

You can override the default options by passing an object in to the .panZoom({options}) call.

Option	Default	Description
panning	true	Enable panning
pinchZoom	true	Enable pinch to zoom
wheelZoom	true	Enable mouse wheel zoom
panButton	0	Which mouse button to use for pan (info)
oneFingerPan	false	Enables the ability to pan with only one finger instead of two for touchdevices
margins	false	An object {top, left, right, bottom} to restrict the pan area towards this side so that at least x user units of the opposite side are still visible
zoomFactor	2	How quickly to zoom when using wheelZoom
zoomMin	Number.MIN_VALUE	The minimum zoom level
zoomMax	Number.MAX_VALUE	The maximum zoom level
wheelZoomDeltaModeLinePixels	17	The multiplier to convert wheel zoom deltaY values from deltaMode=1 (lines) to deltaMode=0 (pixels)
wheelZoomDeltaModeScreenPixels	53	The multiplier to convert wheel zoom deltaY values from deltaMode=2 (screen) to deltaMode=0 (pixels)

Example:

draw.panZoom({
  wheelZoom: false,
  zoomMin: 0.5,
  zoomMax: 2
})

This will disable wheel zooming and set the maximum zoom to 2 or 200% and the minimum zoom to 0.5 or 50%.

Events

Multiple events are fired doing different actions. This allow you to respond to actions and in some cases stop an action via preventDefault().

zoom is fired when a mouse wheel event or pinchZoom triggers a zoom. afterZoom is fired right after the new viewbox was applied and carries the resulting box.

Events fired from SVG.js are CustomEvents, so the arguments passed from svg.panzoom.js are in in the .detail property.

Event Name	Argument Value	preventDefault support
zoom	{ lvl/box, focus }	YES
afterZoom	{ box, focus }	NO
panStart	{ event }	YES
panEnd	{ event }	NO
panning	{ box }	YES
pinchZoomStart	{ event }	YES
pinchZoomEnd	{ event }	NO

panStart is dispatched before the mousedown/touchstart default is prevented, so cancelling it hands the event back to the browser. That is how you keep parts of the drawing interactive - text stays selectable if you refuse to pan when the pointer went down on it:

canvas.on('panStart', (e) => {
  const name = e.detail.event.target.nodeName
  if (name === 'text' || name === 'tspan' || name === 'textPath') {
    e.preventDefault()
  }
})