panzoom

A library for panning and zooming elements using CSS transforms :mag:

2,119

416

2,119

View on GitHub View on NPM

Top Related Projects

panzoom

1,779

Universal pan and zoom library (DOM, SVG, Custom)

svg-pan-zoom

1,742

JavaScript library that enables panning and zooming of an SVG in an HTML document, with mouse events or custom JavaScript hooks

openseadragon

2,994

An open-source, web-based viewer for zoomable images, implemented in pure JavaScript.

dragscroll

1,094

micro library for drag-n-drop scrolling style

zoom

1,543

jQuery plugin for zooming images on mouseover.

Quick Overview

Panzoom is a JavaScript library for adding pan and zoom functionality to HTML elements. It provides a smooth and responsive way to implement zooming and panning on images, maps, or any other content within a web page. The library is lightweight, dependency-free, and works with both mouse and touch events.

Pros

Lightweight and dependency-free, making it easy to integrate into any project
Supports both mouse and touch events for broad device compatibility
Highly customizable with various options and methods for fine-tuning behavior
Smooth performance with hardware acceleration

Cons

Limited built-in UI controls, requiring custom implementation for zoom buttons or sliders
May require additional code for responsive designs or complex layouts
Documentation could be more comprehensive, especially for advanced use cases
No built-in support for SVG elements (though it can be used with some workarounds)

Code Examples

Creating a basic panzoom instance:

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

Zooming programmatically:

// Zoom in by 50%
panzoom.zoomIn(0.5)

// Zoom out to 75% of the original size
panzoom.zoom(0.75)

Panning to a specific position:

// Pan to coordinates (100, 200)
panzoom.pan(100, 200)

Getting Started

Install the library:

npm install @panzoom/panzoom

Import and use in your JavaScript:

import Panzoom from '@panzoom/panzoom'

const elem = document.getElementById('my-element')
const panzoom = Panzoom(elem)

// Add zoom buttons
document.getElementById('zoom-in').addEventListener('click', panzoom.zoomIn)
document.getElementById('zoom-out').addEventListener('click', panzoom.zoomOut)
document.getElementById('reset').addEventListener('click', panzoom.reset)

Ensure your HTML element has a set width and height:

<div id="my-element" style="width: 400px; height: 400px;">
  <img src="image.jpg" />
</div>

Competitor Comparisons

panzoom

1,779

Universal pan and zoom library (DOM, SVG, Custom)

Pros of panzoom (anvaka)

Lightweight and performant, with minimal dependencies
Supports both SVG and HTML elements
Provides smooth animations and easing functions

Cons of panzoom (anvaka)

Less extensive documentation compared to timmywil's version
Fewer built-in options for customization
Limited browser support for older versions

Code Comparison

panzoom (anvaka):

const panzoom = require('panzoom');
const element = document.querySelector('#scene');
panzoom(element, {
  maxZoom: 5,
  minZoom: 0.1
});

panzoom (timmywil):

import Panzoom from '@panzoom/panzoom';
const element = document.querySelector('#scene');
const panzoom = Panzoom(element, {
  maxScale: 5,
  minScale: 0.1
});

Both libraries offer similar core functionality for panning and zooming elements. The anvaka version uses a more concise syntax and focuses on performance, while the timmywil version provides more extensive options and better documentation. The code comparison shows that both libraries have similar initialization processes, with slight differences in naming conventions for options.

svg-pan-zoom

1,742

JavaScript library that enables panning and zooming of an SVG in an HTML document, with mouse events or custom JavaScript hooks

Pros of svg-pan-zoom

Specifically designed for SVG elements, offering optimized performance for vector graphics
Provides built-in methods for controlling zoom and pan programmatically
Includes touch support for mobile devices out of the box

Cons of svg-pan-zoom

Limited to SVG elements, not suitable for general HTML content
Less actively maintained, with fewer recent updates compared to panzoom
Smaller community and fewer contributors, potentially leading to slower issue resolution

Code Comparison

svg-pan-zoom:

var panZoom = svgPanZoom('#svg-id', {
  zoomEnabled: true,
  controlIconsEnabled: true,
  fit: true,
  center: true
});

panzoom:

const elem = document.getElementById('elem')
const panzoom = Panzoom(elem, {
  maxScale: 5,
  minScale: 0.5
})
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)

Both libraries offer simple initialization, but panzoom provides more flexibility for element selection and event handling. svg-pan-zoom offers more SVG-specific options out of the box, while panzoom requires additional setup for similar functionality but can be applied to any HTML element.

openseadragon

2,994

An open-source, web-based viewer for zoomable images, implemented in pure JavaScript.

Pros of OpenSeadragon

More feature-rich, with advanced capabilities for deep zoom and tiling
Better suited for large, high-resolution images and collections
Extensive documentation and active community support

Cons of OpenSeadragon

Larger file size and potentially higher resource usage
Steeper learning curve due to more complex API
May be overkill for simple image viewing needs

Code Comparison

OpenSeadragon:

var viewer = OpenSeadragon({
    id: "openseadragon1",
    prefixUrl: "/openseadragon/images/",
    tileSources: "/path/to/image.dzi"
});

Panzoom:

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

OpenSeadragon is more specialized for deep zoom functionality and complex image viewing scenarios, while Panzoom offers a simpler, lightweight solution for basic pan and zoom needs. OpenSeadragon excels with large, high-resolution images and collections, but may be excessive for simpler use cases. Panzoom, on the other hand, is easier to implement and use for basic image manipulation but lacks advanced features for handling very large images or complex viewing scenarios.

dragscroll

1,094

micro library for drag-n-drop scrolling style

Pros of dragscroll

Lightweight and simple, with minimal setup required
Supports both mouse and touch events for scrolling
Can be applied to any DOM element, not just images

Cons of dragscroll

Limited functionality compared to panzoom (no zooming or programmatic control)
Less customizable and fewer options for fine-tuning behavior
May not perform as well with large or complex elements

Code Comparison

dragscroll:

dragscroll.reset();
dragscroll.addEventListener('mousedown', function(e) {
  e.preventDefault();
});

panzoom:

const elem = document.getElementById('myElement');
const panzoom = Panzoom(elem, {
  maxScale: 5,
  step: 0.5
});
panzoom.pan(10, 10);
panzoom.zoom(2);

The code comparison shows that dragscroll has a simpler API with fewer options, while panzoom offers more control and functionality. dragscroll focuses solely on drag-to-scroll behavior, whereas panzoom provides methods for both panning and zooming, along with various configuration options.

Both libraries serve different purposes: dragscroll is ideal for basic scrolling needs, while panzoom is better suited for more complex interactions requiring both panning and zooming capabilities.

zoom

1,543

jQuery plugin for zooming images on mouseover.

Pros of zoom

Lightweight and simple to use
Supports both jQuery and vanilla JavaScript implementations
Includes touch support for mobile devices

Cons of zoom

Less actively maintained (last update in 2019)
Limited customization options compared to panzoom
Fewer features and less flexibility for complex use cases

Code Comparison

zoom:

$('.zoom').zoom({
  on: 'click',
  magnify: 1.5
});

panzoom:

const elem = document.getElementById('panzoom-element')
const panzoom = Panzoom(elem, {
  maxScale: 5,
  step: 0.5
})
elem.addEventListener('wheel', panzoom.zoomWithWheel)

Key Differences

zoom focuses primarily on image zooming, while panzoom offers more comprehensive pan and zoom functionality
panzoom provides more advanced features like focal point zooming and SVG support
zoom has a simpler API, making it easier to implement for basic use cases
panzoom offers more granular control over zoom behavior and supports programmatic pan/zoom

Use Case Recommendations

Choose zoom for simple image zooming needs, especially if you're already using jQuery
Opt for panzoom when you need more advanced pan and zoom functionality, or if you're working with complex layouts or SVGs

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Panzoom

Examples

Panzoom is a small library (~3.7kb gzipped) to add panning and zooming functionality to an element. Rather than using absolute positioning or setting width and height, Panzoom uses CSS transforms to take advantage of hardware/GPU acceleration in the browser, which means the element can be anything: an image, a video, an iframe, a canvas, text, WHATEVER.

For common support questions, see the FAQ.

Browser support

Here is a list of currently supported browsers.

Mobile support

iOS, Android, and Windows Mobile are supported.

Panzoom includes support for touch gestures and even supports pinch gestures for zooming. It is perfectly suited for both mobile and desktop browsers. It uses pointer events by default wherever supported.

SVG support

Panzoom supports panning and zooming SVG elements directly.

In IE11, CSS animations/transitions do not work on SVG elements, at least for the transform style. They do work in other browsers.

One could implement transitions manually in IE11 using the setTransform option and integrating a tweening library for javascript animations (such as tween.js).

Installing

With npm:

$ npm install --save @panzoom/panzoom

With yarn:

$ yarn add @panzoom/panzoom

Panzoom uses UMD and can be loaded a lot of ways.

With ES6 imports:

import Panzoom from '@panzoom/panzoom'

With commonjs or browserify:

const Panzoom = require('@panzoom/panzoom')

With an AMD loader in an anonymous module:

define(['@panzoom/panzoom'], function (Panzoom) {
  const elem = document.getElementById('panzoom-element')
  Panzoom(elem)
})

With a script tag:

<script src="/js/panzoom.js"></script>

With a script tag from a CDN:

<script src="https://unpkg.com/@panzoom/panzoom@4.5.1/dist/panzoom.min.js"></script>

Usage

const elem = document.getElementById('panzoom-element')
const panzoom = Panzoom(elem, {
  maxScale: 5
})
panzoom.pan(10, 10)
panzoom.zoom(2, { animate: true })

// Panning and pinch zooming are bound automatically (unless disablePan is true).
// There are several available methods for zooming
// that can be bound on button clicks or mousewheel.
button.addEventListener('click', panzoom.zoomIn)
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)

FAQ

1. What is transform-origin and why is it added to the panzoom element?

The transform-origin is the origin from which transforms are applied. Panzoom ensures the defaults are set to what it expects to calculate focal point zooming.
HTML elements default to '50% 50%'.
SVG elements default to '0 0'.

2. I am using Panzoom with an <object> tag and it's not working. What's wrong?

Object elements can eat up events, making it so they never reach Panzoom. To fix this, disable pointer events (pointer-events: none) on the <object> tag and call Panzoom using a wrapper.

3. My links aren't working! How do I enable an anchor within a panzoom element?

Add class options.excludeClass (default is "panzoom-exclude") to whatever element you want to be clickable. Panzoom will check for this class before handling the event. Alternatively, add a reference to the element to the exclude option, or call event.stopImmediatePropagation() in an event handler on the clickable element.

A note on the async nature of Panzoom

In some cases, setting one thing and then setting another synchronously will not work as intended.

For instance, the following usually works fine.

const panzoom = Panzoom(elem)
panzoom.zoom(2)
panzoom.pan(100, 100)

However, you might find that the things start breaking when the contain option is set.

This is due to the fact that in order for Panzoom to retrieve proper dimensions, the scale needs to be painted.

If you find that things aren't looking quite right, try the following instead...

panzoom.zoom(2)
setTimeout(() => panzoom.pan(100, 100))

4. I'm using Panzoom with SVG text elements and am seeing some weird text resizing. How do I fix this?

Add text-rendering="geometricPrecision" to your <text> elements.

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

5. I'm using Panzoom on a canvas element that renders a PDF. How do I avoid the PDF getting blurry when scaled?

See this stackoverflow question

Documentation

Panzoom

â¸ Panzoom(elem, options?): [PanzoomObject](#PanzoomObject)

Parameters

Name	Type
`elem`	`HTMLElement` \| `SVGElement`
`options?`	`Omit`<`[PanzoomOptions](#PanzoomOptions)`, `"force"`>

Returns

[PanzoomObject](#PanzoomObject)

Defined in

panzoom.ts:59

`PanzoomOptions`

Includes MiscOptions, PanOptions, and ZoomOptions

MiscOptions

These options can be passed to Panzoom(), as well as any pan or zoom function. One exception is force, which can only be passed to methods like pan() or zoom(), but not Panzoom() or setOptions() as it should not be set globally.

animate

â¢ Optional animate: boolean (Default: false)

Whether to animate transitions

Defined in

types.ts:21

canvas

â¢ Optional canvas: boolean (Default: false)

This option treats the Panzoom element's parent as a canvas. Effectively, Panzoom binds the down handler to the parent instead of the Panzoom element, so that pointer events anywhere on the "canvas" moves its children. See issue #472.

Note: setting this option to true also changes where the cursor style is applied (i.e. the parent).

Defined in

types.ts:32

duration

â¢ Optional duration: number (Default: 200)

Duration of the transition (ms)

Defined in

types.ts:34

easing

â¢ Optional easing: string (Default: "ease-in-out")

CSS Easing used for transitions

Defined in

types.ts:36

exclude

â¢ Optional exclude: Element[] (Default: [])

Add elements to this array that should be excluded from Panzoom handling. Ancestors of event targets are also checked. e.g. links and buttons that should not propagate the click event.

Defined in

types.ts:43

excludeClass

â¢ Optional excludeClass: string (Default: "panzoom-exclude")

Add this class to any element within the Panzoom element that you want to exclude from Panzoom handling. That element's children will also be excluded. e.g. links and buttons that should not propagate the click event.

Defined in

types.ts:50

force

â¢ Optional force: boolean

force should be used sparingly to temporarily override and ignore options such as disablePan, disableZoom, and panOnlyWhenZoomed. This option cannot be passed to the Panzoom constructor or setOptions (to avoid setting this option globally).

// Overrides disablePan and panOnlyWhenZoomed
panzoom.pan(50, 100, { force: true })
// Overrides disableZoom
panzoom.zoom(1, { force: true })

Defined in

types.ts:66

handleStartEvent

â¢ Optional handleStartEvent: (event: Event) => void (Default: (e: Event) => { e.preventDefault() e.stopPropagation() })

On the first pointer event, when panning starts, the default Panzoom behavior is to call event.preventDefault() and event.stopPropagation() on that event. The former is almost certainly a necessity; the latter enables Panzoom elements within Panzoom elements.

But there are some cases where the default is not the desired behavior. Set this option to override that behavior.

// Only call preventDefault()
Panzoom(elem, {
  handleStartEvent: (event) => {
    event.preventDefault()
  }
})
// Do nothing.
// This can change dragging behavior on mobile.
Panzoom(elem, {
  handleStartEvent: () => {}
})

Parameters

Name	Type
`event`	`Event`

Returns

void

Defined in

types.ts:91

noBind

â¢ Optional noBind: boolean

Skip binding the default Panzoom event listeners

Defined in

types.ts:95

origin

â¢ Optional origin: string

Change this at your own risk. The transform-origin is the origin from which transforms are applied. Default: '50% 50%' for HTML and '0 0' for SVG. The defaults are set because changing the transform-origin on SVG elements doesn't work in IE.

Changing this should work with many things, but it will break focal point zooming, which assumes the defaults are set to do the more complicated calculations.

And again, changing this for SVG in IE doesn't work at all.

Defined in

types.ts:109

overflow

â¢ Optional overflow: string (Default: "hidden")

The overflow CSS value for the parent. Defaults to 'hidden'

Defined in

types.ts:111

pinchAndPan

â¢ Optional pinchAndPan: boolean (Default: false)

Set to true to enable panning during pinch zoom. Note: this is zooming to a point and panning in the same frame. In other words, the zoom has not yet painted and therefore the pan is working with old dimensions. Essentially, it may be best to avoid using this option when using contain.

Defined in

types.ts:124

setTransform

â¢ Optional setTransform: (elem: HTMLElement | SVGElement, __namedParameters: CurrentValues, _options?: PanzoomOptions) => void

Set the transform using the proper prefix

Override the transform setter. This is exposed mostly so the user could set other parts of a transform aside from scale and translate. Default is defined in src/css.ts.

// 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)`)
  }
})

Parameters

Name	Type
`elem`	`HTMLElement` \| `SVGElement`
`__namedParameters`	`CurrentValues`
`_options?`	`PanzoomOptions`

Returns

void

Defined in

types.ts:128

silent

â¢ Optional silent: boolean

Silence all events

Defined in

types.ts:130

startScale

â¢ Optional startScale: number (Default: 1)

Scale used to set the beginning transform

Defined in

types.ts:136

startX

â¢ Optional startX: number (Default: 0)

X Value used to set the beginning transform

Defined in

types.ts:132

startY

â¢ Optional startY: number (Default: 0)

Y Value used to set the beginning transform

Defined in

types.ts:134

touchAction

â¢ Optional touchAction: string (Default: "none")

This value is used to set touch-action on both the Panzoom element and its parent. It is needed because that the native scroll on mobile interferes with panning and pinch zooming. Set this to empty string to re-enable scrolling on mobile, but note that both scrolling and panning cannot work at the same time.

Defined in

types.ts:146

PanOptions (includes MiscOptions)

contain

â¢ Optional contain: "inside" | "outside"

Contain the panzoom element either inside or outside the parent. Inside: The panzoom element is smaller than its parent and cannot be panned to the outside. Outside: The panzoom element is larger than its parent and cannot be panned to the inside. In other words, no empty space around the element will be shown.

Note: the containment pan adjustment is not affected by the disablePan option.

Defined in

types.ts:165

cursor

â¢ Optional cursor: string (Default: "move")

The cursor style to set on the panzoom element

Defined in

types.ts:167

disablePan

â¢ Optional disablePan: boolean (Default: false)

Disable panning functionality. Note: disablePan does not affect focal point zooming or the contain option. The element will still pan accordingly.

Defined in

types.ts:173

disableXAxis

â¢ Optional disableXAxis: boolean (Default: false)

Pan only on the Y axis

Defined in

types.ts:175

disableYAxis

â¢ Optional disableYAxis: boolean (Default: false)

Pan only on the X axis

Defined in

types.ts:177

panOnlyWhenZoomed

â¢ Optional panOnlyWhenZoomed: boolean (Default: false)

Disable panning while the scale is equal to the starting value

Defined in

types.ts:181

relative

â¢ Optional relative: boolean (Default: false)

When passing x and y values to .pan(), treat the values as relative to their current values

Defined in

types.ts:179

roundPixels

â¢ Optional roundPixels: boolean

Round x and y values to whole numbers. This can help prevent images and text from looking blurry, but the higher the scale, the more it becomes necessary to use fractional pixels. Use your own judgment on how much to limit zooming in when using this option.

Defined in

types.ts:190

ZoomOptions (includes MiscOptions)

disableZoom

â¢ Optional disableZoom: boolean (Default: false)

Disable zooming functionality

Defined in

types.ts:195

focal

â¢ Optional focal: Object

Zoom to the given point on the panzoom element. This point is expected to be relative to the panzoom element's dimensions and is unrelated to the parent dimensions.

Type declaration

Name	Type
`x`	`number`
`y`	`number`

Defined in

types.ts:202

maxScale

â¢ Optional maxScale: number (Default: 4)

The maximum scale when zooming

Defined in

types.ts:206

minScale

â¢ Optional minScale: number (Default: 0.125)

The minimum scale when zooming

Defined in

types.ts:204

step

â¢ Optional step: number (Default: 0.3)

The step affects zoom calculation when zooming with a mouse wheel, when pinch zooming, or when using zoomIn/zoomOut

Defined in

types.ts:208

PanzoomObject

These methods are available after initializing Panzoom.

bind

â¢ bind: () => void

Bind the default down, move, and up event listeners to the Panzoom element. This does not normally need to be called. It gets called by default when creating a new Panzoom object, but can be skipped with the noBind option.

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

Returns

void

Defined in

types.ts:235

destroy

â¢ destroy: () => void

Remove all event listeners bound to the the Panzoom element

Returns

void

Defined in

types.ts:237

eventNames

â¢ eventNames: Object

This object exposes the event names used by Panzoom, depending on the current browser's support for Pointer or Touch events.

Type declaration

Name	Type
`down`	`string`
`move`	`string`
`up`	`string`

Defined in

types.ts:243

getOptions

â¢ getOptions: () => PanzoomOptions

Returns a copy of the current options object

Returns

PanzoomOptions

Defined in

types.ts:249

getPan

â¢ getPan: () => { x: number ; y: number }

Get the current x/y translation

Returns

Object

Name	Type
`x`	`number`
`y`	`number`

Defined in

types.ts:245

getScale

â¢ getScale: () => number

Get the current scale

Returns

number

Defined in

types.ts:247

handleDown

â¢ handleDown: (event: PointerEvent) => void

handleDown, handleMove, and handleUp are the exact event handlers that Panzoom binds to pointer events. They are exposed in case you prefer to bind your own events or extend them. Note that move and up are bound to the document, not the Panzoom element. Only the down event is bound to the Panzoom element. To avoid double-binding, also set noBind to true.

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)

Parameters

Name	Type
`event`	`PointerEvent`

Returns

void

Defined in

types.ts:271

handleMove

â¢ handleMove: (event: PointerEvent) => void

Parameters

Name	Type
`event`	`PointerEvent`

Returns

void

Defined in

types.ts:272

handleUp

â¢ handleUp: (event: PointerEvent) => void

Parameters

Name	Type
`event`	`PointerEvent`

Returns

void

Defined in

types.ts:273

pan

â¢ pan: (x: string | number, y: string | number, panOptions?: PanOptions) => [CurrentValues](#CurrentValues)

Pan the Panzoom element to the given x and y coordinates

// Translates the element to 50px, 100px
panzoom.pan(50, 100)
// Pans the element right 10px and down 10px from its current position
panzoom.pan(10, 10, { relative: true })

Parameters

Name	Type
`x`	`string` \| `number`
`y`	`string` \| `number`
`panOptions?`	`PanOptions`

Returns

[CurrentValues](#CurrentValues)

Defined in

types.ts:284

reset

â¢ reset: (resetOptions?: PanzoomOptions) => [CurrentValues](#CurrentValues)

Reset the pan and zoom to startX, startY, and startScale. Animates by default, ignoring the global option. Pass { animate: false } to override. Reset ignores the disablePan, disableZoom, and panOnlyWhenZoomed options. Pass { force: false } to override.

panzoom.reset()
panzoom.reset({ animate: false })

Parameters

Name	Type
`resetOptions?`	`PanzoomOptions`

Returns

[CurrentValues](#CurrentValues)

Defined in

types.ts:297

resetStyle

â¢ resetStyle: () => void

Reset the styles set on the Panzoom element and its parent (such as overflow, cursor, etc.)

panzoom.resetStyle()

Returns

void

Defined in

types.ts:306

setOptions

â¢ setOptions: (options?: PanzoomOptions) => void

Change any number of options on a Panzoom instance. Setting some options will have side-effects. For instance, changing the cursor option will also set the cursor style.

const panzoom = Panzoom(elem, { cursor: 'move' })
// ...
panzoom.setOptions({ cursor: 'default' })

Parameters

Name	Type
`options?`	`PanzoomOptions`

Returns

void

Defined in

types.ts:319

setStyle

â¢ setStyle: (name: string, value: string) => void

A convenience method for setting prefixed styles on the Panzoom element

Parameters

Name	Type
`name`	`string`
`value`	`string`

Returns

void

Defined in

types.ts:321

zoom

â¢ zoom: (scale: number, zoomOptions?: ZoomOptions) => [CurrentValues](#CurrentValues)

Zoom the Panzoom element to the given scale

panzoom.zoom(2.2)
panzoom.zoom(2.2, { animate: true })

Parameters

Name	Type
`scale`	`number`
`zoomOptions?`	`ZoomOptions`

Returns

[CurrentValues](#CurrentValues)

Defined in

types.ts:330

zoomIn

â¢ zoomIn: (zoomOptions?: ZoomOptions) => [CurrentValues](#CurrentValues)

Zoom in using the predetermined increment set in options. Animates by default, ignoring the global option. Pass { animate: false } to override.

panzoom.zoomIn()
panzoom.zoomIn({ animate: false })

Parameters

Name	Type
`zoomOptions?`	`ZoomOptions`

Returns

[CurrentValues](#CurrentValues)

Defined in

types.ts:341

zoomOut

â¢ zoomOut: (zoomOptions?: ZoomOptions) => [CurrentValues](#CurrentValues)

Zoom out using the predetermined increment set in options. Animates by default, ignoring the global option. Pass { animate: false } to override.

panzoom.zoomOut()
panzoom.zoomOut({ animate: false })

Parameters

Name	Type
`zoomOptions?`	`ZoomOptions`

Returns

[CurrentValues](#CurrentValues)

Defined in

types.ts:352

zoomToPoint

â¢ zoomToPoint: (scale: number, point: { clientX: number ; clientY: number }, zoomOptions?: ZoomOptions) => [CurrentValues](#CurrentValues)

Zoom the Panzoom element to a focal point using the given pointer/touch/mouse event or constructed point. The clientX/clientY values should be calculated the same way as a pointermove event on the Panzoom element's parent.

panzoom.zoomToPoint(1.2, pointerEvent)

Parameters

Name	Type
`scale`	`number`
`point`	`Object`
`point.clientX`	`number`
`point.clientY`	`number`
`zoomOptions?`	`ZoomOptions`

Returns

[CurrentValues](#CurrentValues)

Defined in

types.ts:363

zoomWithWheel

â¢ zoomWithWheel: (event: WheelEvent, zoomOptions?: ZoomOptions) => [CurrentValues](#CurrentValues)

Zoom the Panzoom element to a focal point using the given WheelEvent

This is a convenience function that may not handle all use cases. Other cases should handroll solutions using the zoomToPoint method or the zoom method's focal option.

Notes:

the focal point zooming pan adjustment is not affected by the disablePan option.
animate should not be used when zooming with the wheel, and is therefore always disabled.

// Bind to mousewheel
elem.parentElement.addEventListener('wheel', panzoom.zoomWithWheel)
// Bind to shift+mousewheel
elem.parentElement.addEventListener('wheel', function (event) {
  if (!event.shiftKey) return
  // Panzoom will automatically use `deltaX` here instead
  // of `deltaY`. On a mac, the shift modifier usually
  // translates to horizontal scrolling, but Panzoom assumes
  // the desired behavior is zooming.
  panzoom.zoomWithWheel(event)
})

Parameters

Name	Type
`event`	`WheelEvent`
`zoomOptions?`	`ZoomOptions`

Returns

[CurrentValues](#CurrentValues)

Defined in

types.ts:396

CurrentValues

isSVG

â¢ Optional isSVG: boolean

Defined in

types.ts:219

scale

â¢ scale: number

Defined in

types.ts:218

x

â¢ x: number

Defined in

types.ts:216

y

â¢ y: number

Defined in

types.ts:217

Events

The following events are available as custom events on the panzoom element using the native CustomEvent API. Add listeners the same way you would any other event.

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

Notes about all events

The event object passed as an argument to the listener will always have a detail object with the following properties:
- The current x value
- The current y value
- The current scale
- An originalEvent property with the original event that triggered the panzoom event, if applicable. For example, the originalEvent property for a panzoomstart event would be either a pointerdown, touchstart, or mousedown event.
Events can be silenced when the silent option is set to true, either globally or when passed to pan, any zoom method, or reset.
Avoid putting too much logic in these event handlers as it could effect the performance of panning or zooming.

`"panzoomstart"`

Fired when the user starts a move or pinch zoom gesture on mobile.

`"panzoomchange"`

Fired whenever there is a pan, zoom, or reset. Note that direct calls to options.setTransform do not fire this event.

`"panzoomzoom"`

Fired whenever the zoom is changed by any Panzoom zoom method, directly or internally.

`"panzoompan"`

Fired whenever the pan is changed by the pan method, directly or internally.

`"panzoomend"`

Fired when the user finishes a move or finishes a pinch zoom gesture on mobile.

`"panzoomreset"`

Fired whenever reset is called.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot