Panzoom

Examples

This rewrite is a work in progress

Have a look at the GitHub project to follow along on the status of this rewrite.

---

Panzoom is a small library 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.

panzoom.min.js, included in this repo, is compressed with uglifyjs.

For common support questions, see the FAQ at the bottom.

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

Loading Panzoom

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

With ES6 imports:

import Panzoom from 'panzoom'

With AMD loader in an anonymous module:

define(['panzoom'], function(Panzoom) {
  Panzoom('.panzoom')
})

With script tags:

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

Initialization

const panzoom = Panzoom('.panzoom', {
  maxScale: 5
})

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. It zooms but does not pan. example

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.clickableClass (default is "clickable") to whatever element you want to be clickable. Panzoom will check for this class before handling the event. You can also call event.stopImmediatePropagation() in an event handler on the clickable element.

---

Documentation

Default export

▸ Panzoom(elem: HTMLElement | SVGElement, options?: PanzoomOptions): PanzoomObject

Defined in panzoom.ts:38

Parameters:

Name	Type
elem	HTMLElement | SVGElement
options?	PanzoomOptions

Returns: PanzoomObject

Const defaultOptions

Defined in panzoom.ts:18

animate

• animate: false = false

Defined in panzoom.ts:19

clickableClass

• clickableClass: string = "clickable"

Defined in panzoom.ts:20

cursor

• cursor: string = "move"

Defined in panzoom.ts:21

disablePan

• disablePan: false = false

Defined in panzoom.ts:22

disableXAxis

• disableXAxis: false = false

Defined in panzoom.ts:24

disableYAxis

• disableYAxis: false = false

Defined in panzoom.ts:25

disableZoom

• disableZoom: false = false

Defined in panzoom.ts:23

duration

• duration: number = 200

Defined in panzoom.ts:26

easing

• easing: string = "ease-in-out"

Defined in panzoom.ts:27

maxScale

• maxScale: number = 4

Defined in panzoom.ts:28

minScale

• minScale: number = 0.125

Defined in panzoom.ts:29

relative

• relative: false = false

Defined in panzoom.ts:30

setTransform

• setTransform: setTransform

Defined in panzoom.ts:31

startScale

• startScale: number = 1

Defined in panzoom.ts:34

startX

• startX: number = 0

Defined in panzoom.ts:32

startY

• startY: number = 0

Defined in panzoom.ts:33

step

• step: number = 0.3

Defined in panzoom.ts:35

PanzoomOptions

Includes MiscOptions, PanOptions, and ZoomOptions

---

MiscOptions

Optional animate

• animate? : boolean

Defined in types.ts:5

Whether to animate transitions

---

Optional clickableClass

• clickableClass? : string

Defined in types.ts:10

Add this class to any element within the panzoom element that you want to be clickable and not initiate the drag

---

Optional duration

• duration? : number

Defined in types.ts:12

Duration of the transition (ms)

---

Optional easing

• easing? : string

Defined in types.ts:14

CSS Easing used for transitions

---

Optional origin

• origin? : string

Defined in types.ts:28

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.

---

Optional setTransform

• setTransform? : setTransform

Defined in types.ts:45

Override the transform setter. This is exposed mostly so the user could set other parts of a transform aside from scale and translate.

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

---

Optional startScale

• startScale? : number

Defined in types.ts:49

---

Optional startX

• startX? : number

Defined in types.ts:47

Values used to set the beginning transform

---

Optional startY

• startY? : number

Defined in types.ts:48

---

PanOptions

Includes MiscOptions

Optional contain

• contain? : "inside" | "outside"

Defined in types.ts:66

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.

---

Optional cursor

• cursor? : string

Defined in types.ts:68

The cursor style to set on the panzoom element

---

Optional disablePan

• disablePan? : boolean

Defined in types.ts:70

Disable panning functionality. Note: disablePan also disables focal point zooming

---

Optional disableXAxis

• disableXAxis? : boolean

Defined in types.ts:72

Pan only on the Y axis

---

Optional disableYAxis

• disableYAxis? : boolean

Defined in types.ts:74

Pan only on the X axis

---

Optional panOnlyWhenZoomed

• panOnlyWhenZoomed? : boolean

Defined in types.ts:78

Disable panning while the scale is equal to the starting value

---

Optional relative

• relative? : boolean

Defined in types.ts:76

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

---

ZoomOptions

Includes MiscOptions

Optional disableZoom

• disableZoom? : boolean

Defined in types.ts:83

Disable zooming functionality

---

Optional focal

• focal? : object

Defined in types.ts:90

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:

• x: number

• y: number

---

Optional maxScale

• maxScale? : number

Defined in types.ts:94

The maximum scale when zooming

---

Optional minScale

• minScale? : number

Defined in types.ts:92

The minimum scale when zooming

---

Optional step

• step? : number

Defined in types.ts:96

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

---

PanzoomObject

These methods are available after initializing Panzoom

getOptions

• getOptions: function

Defined in types.ts:117

Returns a copy of the current options object

Signature with return type:

▸ (): PanzoomOptions

---

getPan

• getPan: function

Defined in types.ts:113

Get the current x/y translation

Signature with return type:

▸ (): object

• x: number

• y: number

---

getScale

• getScale: function

Defined in types.ts:115

Get the current scale

Signature with return type:

▸ (): number

---

pan

• pan: function

Defined in types.ts:128

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

Signature with return type:

▸ (x: number | string, y: number | string, panOptions?: PanOptions): CurrentValues

Parameters:

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

---

reset

• reset: function

Defined in types.ts:134

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

Signature with return type:

▸ (resetOptions?: PanzoomOptions): CurrentValues

Parameters:

Name	Type
resetOptions?	PanzoomOptions

---

setOptions

• setOptions: function

Defined in types.ts:136

Change options for the Panzoom instance

Signature with return type:

▸ (options?: PanzoomOptions): void

Parameters:

Name	Type
options?	PanzoomOptions

---

setStyle

• setStyle: setStyle

Defined in types.ts:138

A convenience method for setting prefixed styles on the Panzoom element

---

zoom

• zoom: function

Defined in types.ts:147

Zoom the Panzoom element to the given scale

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

Signature with return type:

▸ (scale: number, zoomOptions?: ZoomOptions): CurrentValues

Parameters:

Name	Type
scale	number
zoomOptions?	ZoomOptions

---

zoomIn

• zoomIn: function

Defined in types.ts:153

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

Signature with return type:

▸ (zoomOptions?: ZoomOptions): CurrentValues

Parameters:

Name	Type
zoomOptions?	ZoomOptions

---

zoomOut

• zoomOut: function

Defined in types.ts:159

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

Signature with return type:

▸ (zoomOptions?: ZoomOptions): CurrentValues

Parameters:

Name	Type
zoomOptions?	ZoomOptions

---

zoomToPoint

• zoomToPoint: function

Defined in types.ts:166

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 pointer event on the Panzoom element.

Signature with return type:

▸ (scale: number, point: object, zoomOptions?: ZoomOptions): CurrentValues

Parameters:

▪ scale: number

▪ point: object

Name	Type
clientX	number
clientY	number

▪Optional zoomOptions: ZoomOptions

---

zoomWithWheel

• zoomWithWheel: function

Defined in types.ts:195

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

disablePan will prevent the focal point adjustment and will only zoom.

zoomWithWheel normally uses deltaY to determine the scale, but will fall back to deltaX in case the shift modifier is used with the wheel event. On a mac, that usually translates to horizontal scrolling, but this method assumes the desired behavior is zooming.

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.

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

Signature with return type:

▸ (event: WheelEvent, zoomOptions?: ZoomOptions): CurrentValues

Parameters:

Name	Type
event	WheelEvent
zoomOptions?	ZoomOptions

---

CurrentValues

scale

• scale: number

Defined in types.ts:108

---

x

• x: number

Defined in types.ts:106

---

y

• y: number

Defined in types.ts:107