{"id":15161,"library":"panzoom","title":"DOM and SVG Pan and Zoom","description":"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.","status":"active","version":"9.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/anvaka/panzoom","tags":["javascript","dom","svg","pan","zoom","typescript"],"install":[{"cmd":"npm install panzoom","lang":"bash","label":"npm"},{"cmd":"yarn add panzoom","lang":"bash","label":"yarn"},{"cmd":"pnpm add panzoom","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `panzoom` function is a default export, not a named export.","wrong":"import { panzoom } from 'panzoom';","symbol":"panzoom","correct":"import panzoom from 'panzoom';"},{"note":"For CommonJS environments (Node.js or older bundlers), use `require`.","symbol":"panzoom (CommonJS)","correct":"const panzoom = require('panzoom');"},{"note":"When imported via CDN `\n\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Store the panzoom instance returned by `panzoom(element)` and call `instance.dispose()` when the element or component is no longer needed.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the `beforeKeyDown` option to filter or disable keyboard events: `panzoom(element, { beforeKeyDown: (e) => !e.metaKey });`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Configure panzoom with `beforeWheel: function(e) { return !e.altKey; }` to only allow zoom when the Alt key is pressed.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be aware of the limitation; if touch panning also needs filtering, it must be handled separately or within a custom input plugin.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Incorrect import statement or `panzoom` not loaded correctly (e.g., CDN script after script that uses it).","error":"TypeError: panzoom is not a function"},{"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.","cause":"The target element for panzoom is incorrect, or custom `beforeMouseDown`/`beforeWheel` filters are preventing interaction.","error":"Element does not pan or zoom (no errors in console)"},{"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.","cause":"The `dispose()` method was not called on a panzoom instance that is no longer needed.","error":"Memory usage increases over time or event handlers persist after element removal."}],"ecosystem":"npm"}