DOM and SVG Pan and Zoom

9.4.4 · active · verified Tue Apr 21

panzoom is a standalone, extensible JavaScript library designed to add intuitive pan and zoom functionalities to both regular DOM elements and SVG graphics. Currently stable at version 9.4.4, the project is actively maintained, with incremental updates focusing on stability and feature enhancements. It offers a highly configurable API, allowing developers to customize interaction behaviors, such as filtering mouse wheel or mouse down events to prevent conflicts with page scrolling or other interactions. A key differentiator is its framework-agnostic design, directly manipulating the target element without imposing dependencies on specific UI frameworks, making it exceptionally versatile for embedding into any web application. It provides a comprehensive event system for tracking pan, zoom, and general transform changes, and importantly, includes a `dispose()` method to ensure proper cleanup of event listeners and prevent memory leaks, which is crucial for dynamic applications. The library ships with TypeScript types, enhancing developer experience in type-safe environments.

Common errors

```
TypeError: panzoom is not a function
```
cause Incorrect import statement or `panzoom` not loaded correctly (e.g., CDN script after script that uses it).

fix Ensure you are using `import panzoom from 'panzoom';` for ESM, `const panzoom = require('panzoom');` for CommonJS, or that the CDN script loaded successfully and `window.panzoom` is available.
```
Element does not pan or zoom (no errors in console)
```
cause The target element for panzoom is incorrect, or custom `beforeMouseDown`/`beforeWheel` filters are preventing interaction.

fix Verify that `document.querySelector` or `document.getElementById` returns the intended element. Check any custom `beforeMouseDown` or `beforeWheel` functions to ensure they are not inadvertently returning `true` (to ignore the event) when interaction is desired.
```
Memory usage increases over time or event handlers persist after element removal.
```
cause The `dispose()` method was not called on a panzoom instance that is no longer needed.

fix Whenever an element managed by panzoom is removed from the DOM, or a component using panzoom is unmounted, call `instance.dispose()` on the associated panzoom instance to release resources.

Warnings

gotcha When dynamically adding/removing panzoom instances or managing component lifecycles, always call `instance.dispose()` to prevent memory leaks. This cleans up all event listeners and internal resources.
Fix: Store the panzoom instance returned by `panzoom(element)` and call `instance.dispose()` when the element or component is no longer needed.
gotcha By default, panzoom listens to keyboard events for navigation (`arrows`, `+`, `-`). If these conflict with other page interactions or desired keyboard shortcuts, you may need to disable them or provide custom filters.
Fix: Use the `beforeKeyDown` option to filter or disable keyboard events: `panzoom(element, { beforeKeyDown: (e) => !e.metaKey });`
gotcha Mouse wheel zooming can conflict with page scrolling. To avoid this, use the `beforeWheel` option to require a modifier key (e.g., `Alt`) for zooming.
Fix: Configure panzoom with `beforeWheel: function(e) { return !e.altKey; }` to only allow zoom when the Alt key is pressed.
gotcha The `beforeMouseDown` option only applies to mouse-initiated panning, not touch events. For consistent behavior across input types, consider combining `beforeMouseDown` with custom touch event handling.
Fix: Be aware of the limitation; if touch panning also needs filtering, it must be handled separately or within a custom input plugin.

Install

npm install panzoom npm
yarn add panzoom yarn
pnpm add panzoom pnpm

Imports

panzoom
wrong:
```
import { panzoom } from 'panzoom';
```
correct:
```
import panzoom from 'panzoom';
```
The primary `panzoom` function is a default export, not a named export.
panzoom (CommonJS)
```
const panzoom = require('panzoom');
```
For CommonJS environments (Node.js or older bundlers), use `require`.
panzoom (CDN Global)
```
const instance = window.panzoom(element);
```
When imported via CDN `<script>` tag, `panzoom` is available as a global variable on the `window` object.

Quickstart

This quickstart demonstrates how to apply pan and zoom functionality to a simple HTML element, including basic configuration options and event filtering for mouse wheel.

<html>
<head>
  <title>Panzoom Demo</title>
  <style>
    #container {
      width: 400px;
      height: 300px;
      border: 1px solid #ccc;
      overflow: hidden;
      position: relative;
    }
    #scene {
      width: 200px;
      height: 150px;
      background: lightblue;
      position: absolute;
      top: 50px;
      left: 50px;
      transform-origin: 0 0;
    }
  </style>
</head>
<body>
  <div id="container">
    <div id="scene">Drag and Zoom Me</div>
  </div>
  <script type="module">
    import panzoom from 'panzoom';

    const container = document.getElementById('container');
    const scene = document.getElementById('scene');

    const pz = panzoom(scene, {
      bounds: true,
      boundsPadding: 0.1,
      maxZoom: 4,
      minZoom: 0.5,
      // Example of custom filter: only zoom with Alt key pressed
      beforeWheel: function(e) {
        return !e.altKey;
      }
    });

    console.log('Panzoom initialized:', pz);

    // Optional: Dispose after some time or on element removal
    // setTimeout(() => {
    //   pz.dispose();
    //   console.log('Panzoom disposed.');
    // }, 10000);
  </script>
</body>
</html>

view raw JSON →