Panzoom
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:
With commonjs or browserify:
const Panzoom =
With an AMD loader in an anonymous module:
With a script tag:
Usage
const elem = documentconst panzoom = panzoompanzoom // 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.buttonelemparentElement
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 = panzoompanzoom
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
Documentation
▸ Panzoom(elem
: HTMLElement | SVGElement, options?
: Omit‹PanzoomOptions, "force"›): PanzoomObject
Defined in panzoom.ts:51
Parameters:
Name | Type |
---|---|
elem |
HTMLElement | SVGElement |
options? |
Omit‹PanzoomOptions, "force"› |
Returns: PanzoomObject
PanzoomOptions
Includes MiscOptions
, PanOptions
, and ZoomOptions
MiscOptions
animate
• animate? : boolean (Default: false)
Defined in types.ts:13
Whether to animate transitions
canvas
• canvas? : boolean (Default: false)
Defined in types.ts:24
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).
duration
• duration? : number (Default: 200)
Defined in types.ts:26
Duration of the transition (ms)
easing
• easing? : string (Default: "ease-in-out")
Defined in types.ts:28
CSS Easing used for transitions
exclude
• exclude? : Element[]
Defined in types.ts:35
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.
excludeClass
• excludeClass? : string (Default: "panzoom-exclude")
Defined in types.ts:42
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.
force
• force? : boolean
Defined in types.ts:58
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 panOnlyWhenZoomedpanzoom// Overrides disableZoompanzoom
handleStartEvent
• handleStartEvent? : function
Defined in types.ts:83
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()// Do nothing.// This can change dragging behavior on mobile.
Type declaration:
▸ (event
: Event): void
Parameters:
Name | Type |
---|---|
event |
Event |
noBind
• noBind? : boolean
Defined in types.ts:87
Skip binding the default Panzoom event listeners
origin
• origin? : string
Defined in types.ts:101
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.
overflow
• overflow? : string (Default: "hidden")
Defined in types.ts:103
The overflow CSS value for the parent. Defaults to 'hidden'
setTransform
• setTransform? : typeof setTransform
Defined in types.ts:121
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 translationconst panzoom =
silent
• silent? : boolean
Defined in types.ts:123
Silence all events
startScale
• startScale? : number (Default: 1)
Defined in types.ts:129
Scale used to set the beginning transform
startX
• startX? : number (Default: 0)
Defined in types.ts:125
X Value used to set the beginning transform
startY
• startY? : number (Default: 0)
Defined in types.ts:127
Y Value used to set the beginning transform
touchAction
• touchAction? : string (Default: "none")
Defined in types.ts:139
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.
PanOptions
Includes MiscOptions
contain
• contain? : "inside" | "outside"
Defined in types.ts:158
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.
cursor
• cursor? : string (Default: "move")
Defined in types.ts:160
The cursor style to set on the panzoom element
disablePan
• disablePan? : boolean (Default: false)
Defined in types.ts:166
Disable panning functionality. Note: disablePan does not affect focal point zooming or the contain option. The element will still pan accordingly.
disableXAxis
• disableXAxis? : boolean (Default: false)
Defined in types.ts:168
Pan only on the Y axis
disableYAxis
• disableYAxis? : boolean (Default: false)
Defined in types.ts:170
Pan only on the X axis
panOnlyWhenZoomed
• panOnlyWhenZoomed? : boolean (Default: false)
Defined in types.ts:174
Disable panning while the scale is equal to the starting value
relative
• relative? : boolean (Default: false)
Defined in types.ts:172
When passing x and y values to .pan(), treat the values as relative to their current values
ZoomOptions
Includes MiscOptions
disableZoom
• disableZoom? : boolean (Default: false)
Defined in types.ts:179
Disable zooming functionality
focal
• focal? : object
Defined in types.ts:186
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
maxScale
• maxScale? : number (Default: 4)
Defined in types.ts:190
The maximum scale when zooming
minScale
• minScale? : number (Default: 0.125)
Defined in types.ts:188
The minimum scale when zooming
step
• step? : number (Default: 0.3)
Defined in types.ts:192
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
bind()
• bind: function
Defined in types.ts:213
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.
Signature with return type:
▸ (): void
destroy()
• destroy: function
Defined in types.ts:215
Remove all event listeners bound to the the Panzoom element
Signature with return type:
▸ (): void
eventNames()
• eventNames: object
Defined in types.ts:221
This object exposes the event names used by Panzoom, depending on the current browser's support for Pointer or Touch events.
Signature with return type:
-
down: string
-
move: string
-
up: string
getOptions()
• getOptions: function
Defined in types.ts:227
Returns a copy of the current options object
Signature with return type:
▸ (): PanzoomOptions
getPan()
• getPan: function
Defined in types.ts:223
Get the current x/y translation
Signature with return type:
▸ (): object
-
x: number
-
y: number
getScale()
• getScale: function
Defined in types.ts:225
Get the current scale
Signature with return type:
▸ (): number
pan()
• pan: function
Defined in types.ts:238
Pan the Panzoom element to the given x and y coordinates
// Translates the element to 50px, 100pxpanzoom// Pans the element right 10px and down 10px from its current positionpanzoom
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:251
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.
panzoompanzoom
Signature with return type:
▸ (resetOptions?
: PanzoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
resetOptions? |
PanzoomOptions |
setOptions()
• setOptions: function
Defined in types.ts:253
Change options for the Panzoom instance
Signature with return type:
▸ (options?
: PanzoomOptions): void
Parameters:
Name | Type |
---|---|
options? |
PanzoomOptions |
setStyle()
• setStyle: function
Defined in types.ts:255
A convenience method for setting prefixed styles on the Panzoom element
Signature with return type:
▸ (name
: string, value
: string): void
Parameters:
Name | Type |
---|---|
name |
string |
value |
string |
zoom()
• zoom: function
Defined in types.ts:264
Zoom the Panzoom element to the given scale
panzoompanzoom
Signature with return type:
▸ (scale
: number, zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
scale |
number |
zoomOptions? |
ZoomOptions |
zoomIn()
• zoomIn: function
Defined in types.ts:275
Zoom in using the predetermined increment set in options.
Animates by default, ignoring the global option.
Pass { animate: false }
to override.
panzoompanzoom
Signature with return type:
▸ (zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
zoomOptions? |
ZoomOptions |
zoomOut()
• zoomOut: function
Defined in types.ts:286
Zoom out using the predetermined increment set in options.
Animates by default, ignoring the global option.
Pass { animate: false }
to override.
panzoompanzoom
Signature with return type:
▸ (zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
zoomOptions? |
ZoomOptions |
zoomToPoint()
• zoomToPoint: function
Defined in types.ts:297
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
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:326
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.
Note: the focal point zooming pan adjustment is not affected by the disablePan
option.
// Bind to mousewheelelemparentElement// Bind to shift+mousewheelelemparentElement
Signature with return type:
▸ (event
: WheelEvent, zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
event |
WheelEvent |
zoomOptions? |
ZoomOptions |
CurrentValues
Optional
isSVG
• isSVG? : boolean
Defined in types.ts:203
scale
• scale: number
Defined in types.ts:202
x
• x: number
Defined in types.ts:200
y
• y: number
Defined in types.ts:201
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
Notes about all events
- The event object passed as an argument to the listener will always have a
detail
property with the currentx
,y
, andscale
values. - Events can be silenced when the
silent
option is set totrue
, either globally or when passed topan
, anyzoom
method, orreset
. - 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.