panzoom

library0.1.2jsnpmunverified

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.

web-framework

npm install panzoom

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PANZOOM

panzoom

web-frameworkjavascriptv0.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

panzoom

✓ import panzoom from 'panzoom';

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

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>

Debug

Known issues

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

affects: >=1.0.0

gotchaBy 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 });`

affects: >=1.0.0

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

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: panzoom is not a function

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)

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.

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.

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/anvaka/panzoom ↗

packagehttps://www.npmjs.com/package/panzoom ↗

homepagehttps://timmywil.com/dev/panzoom/ ↗