Panzoom

Every Panzoom event provides a detail object containing the current transformation state and the triggering event. The properties available in detail are:

• x: The current x-coordinate.
• y: The current y-coordinate.
• scale: The current zoom scale.
• originalEvent: The original browser event that triggered the panzoom action (e.g., pointerdown, touchstart, or mousedown). This is applicable for events like panzoomstart and panzoomend.

You can prevent Panzoom events from firing by setting the silent option to true. This can be done:

1. Globally during initialization.
2. Locally by passing { silent: true } to specific method calls like pan(), zoom(), or reset().

When the contain option is enabled, Panzoom needs to retrieve element dimensions, which requires the scale to be painted. If you attempt to call zoom() and pan() synchronously, the second call might fail or behave unexpectedly. In these cases, use a setTimeout to ensure the scale has been applied before panning.

// If things aren't looking right when using 'contain':
panzoom.zoom(2)
setTimeout(() => panzoom.pan(100, 100))

Panzoom emits custom events on the element it is controlling. You can listen to these using the native addEventListener API. The event object passed to the listener contains a detail object with the current state of the element.

elem.addEventListener('panzoomchange', (event) => {
  console.log(event.detail) // => { x: 0, y: 0, scale: 1 }
})

You can install Panzoom using npm or yarn. It is a small library (~3.7kb gzipped) that uses CSS transforms for hardware-accelerated panning and zooming of any element (images, videos, iframes, canvas, text, etc.).

$ npm install --save @panzoom/panzoom

# or

$ yarn add @panzoom/panzoom

If you need to control how events are captured (e.g., to integrate with a specific framework or custom event logic), you can use the handleDown, handleMove, and handleUp methods.

To avoid double-binding when using these manually, initialize Panzoom with the noBind: true option. Note that handleDown is bound to the Panzoom element, while handleMove and handleUp are typically bound to the document to ensure smooth interaction when the pointer leaves the element.

const panzoom = Panzoom(elem, { noBind: true })

elem.addEventListener('pointerdown', (event) => {
  console.log(event)
  panzoom.handleDown(event)
})

document.addEventListener('pointermove', panzoom.handleMove)
document.addEventListener('pointerup', panzoom.handleUp)

By default, Panzoom handles events in a way that might prevent links or anchors from working. To make specific elements clickable, you have three options:

1. Add the class specified in options.excludeClass (the default is "panzoom-exclude") to the element.
2. Add a reference to the element to the exclude option in the Panzoom configuration.
3. Call event.stopImmediatePropagation() in an event handler on the clickable element.

If you are using Panzoom with SVG <text> elements and encounter weird resizing behavior, add the text-rendering="geometricPrecision" attribute to your text elements.

<text text-rendering="geometricPrecision" x="40" y="120">Hello World</text>

You can override the default transform setter to include additional CSS properties like rotation. The callback receives the element, the current values (scale, x, y), and the options.

// This example always sets a rotation
// when setting the scale and translation
const panzoom = Panzoom(elem, {
  setTransform: (elem, { scale, x, y }) => {
    panzoom.setStyle('transform', `rotate(0.5turn) scale(${scale}) translate(${x}px, ${y}px)`)
  }
})

The zoomWithWheel method provides a convenient way to implement zooming via the mouse wheel. It should be attached to the element's parent to capture wheel events effectively.

Note:

• The focal point adjustment is not affected by the disablePan option.
• animate is always disabled when using this method.
• On some devices (like Mac), shift + wheel might be interpreted as horizontal scrolling; Panzoom assumes the user intends to zoom in these cases.

// Bind to mousewheel
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)

// Bind to shift+mousewheel
elem.parentElement.addEventListener('wheel', function (event) {
  if (!event.shiftKey) return
  panzoom.zoomWithWheel(event)
})

To use Panzoom, initialize it by passing an element and an optional configuration object. Panzoom automatically binds panning and pinch-to-zoom gestures (unless disablePan is set to true). You can also manually control zooming via methods like zoomIn or zoomWithWheel.

const elem = document.getElementById('panzoom-element')
const panzoom = Panzoom(elem, {
  maxScale: 5
})

// Manual control
panzoom.pan(10, 10)
panzoom.zoom(2, { animate: true })

// Binding to UI elements
button.addEventListener('click', panzoom.zoomIn)
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)