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 (~3kb 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.
Here is a list of currently supported browsers.
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.
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).
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) {
Panzoom('.panzoom')
})
With a script tag:
<script src="/js/panzoom.js"></script>
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)
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.clickableClass
(default is "clickable"
) to whatever element you want to be clickable. Panzoom will check for this class before handling the event.
Alternatively, call event.stopImmediatePropagation()
in an event handler on the clickable element.
▸ Panzoom(elem
: HTMLElement
| SVGElement
, options?
: PanzoomOptions): PanzoomObject
Defined in panzoom.ts:40
Parameters:
Name | Type |
---|---|
elem |
HTMLElement | SVGElement |
options? |
PanzoomOptions |
Returns: PanzoomObject
Includes MiscOptions
, PanOptions
, and ZoomOptions
• animate? : boolean (Default: false)
Defined in types.ts:5
Whether to animate transitions
• clickableClass? : string (Default: "clickable")
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
• duration? : number (Default: 200)
Defined in types.ts:12
Duration of the transition (ms)
• easing? : string (Default: "ease-in-out")
Defined in types.ts:14
CSS Easing used for transitions
• 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.
• setTransform? : setTransform
Defined in types.ts:46
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
Panzoom(elem, {
setTransform: (elem, { scale, x, y }) => {
setStyle(elem, 'transform', `rotate(0.5turn) scale(${scale}) translate(${x}px, ${y}px)`)
}
})
• silent? : boolean
Defined in types.ts:48
Silence all events
• startScale? : number (Default: 1)
Defined in types.ts:54
Scale used to set the beginning transform
• startX? : number (Default: 0)
Defined in types.ts:50
X Value used to set the beginning transform
• startY? : number (Default: 0)
Defined in types.ts:52
Y Value used to set the beginning transform
Includes MiscOptions
• contain? : "inside" | "outside"
Defined in types.ts:71
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.
• cursor? : string (Default: "move")
Defined in types.ts:73
The cursor style to set on the panzoom element
• disablePan? : boolean (Default: false)
Defined in types.ts:75
Disable panning functionality. Note: disablePan also disables focal point zooming
• disableXAxis? : boolean (Default: false)
Defined in types.ts:77
Pan only on the Y axis
• disableYAxis? : boolean (Default: false)
Defined in types.ts:79
Pan only on the X axis
• panOnlyWhenZoomed? : boolean (Default: false)
Defined in types.ts:83
Disable panning while the scale is equal to the starting value
• relative? : boolean (Default: false)
Defined in types.ts:81
When passing x and y values to .pan(), treat the values as relative to their current values
Includes MiscOptions
• disableZoom? : boolean (Default: false)
Defined in types.ts:88
Disable zooming functionality
• focal? : object
Defined in types.ts:95
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.
-
x: number
-
y: number
• maxScale? : number (Default: 4)
Defined in types.ts:99
The maximum scale when zooming
• minScale? : number (Default: 0.125)
Defined in types.ts:97
The minimum scale when zooming
• step? : number (Default: 0.3)
Defined in types.ts:101
The step affects zoom calculation when zooming with a mouse wheel, when pinch zooming, or when using zoomIn/zoomOut
These methods are available after initializing Panzoom
• getOptions: function
Defined in types.ts:122
Returns a copy of the current options object
▸ (): PanzoomOptions
• getPan: function
Defined in types.ts:118
Get the current x/y translation
▸ (): object
-
x: number
-
y: number
• getScale: function
Defined in types.ts:120
Get the current scale
▸ (): number
• pan: function
Defined in types.ts:133
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 })
▸ (x
: number | string, y
: number | string, panOptions?
: PanOptions): CurrentValues
Parameters:
Name | Type |
---|---|
x |
number | string |
y |
number | string |
panOptions? |
PanOptions |
• reset: function
Defined in types.ts:144
Reset the pan and zoom to startX, startY, and startScale.
Animates by default, ignoring the global option.
Pass { animate: false }
to override.
panzoom.reset()
panzoom.reset({ animate: false })
▸ (resetOptions?
: PanzoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
resetOptions? |
PanzoomOptions |
• setOptions: function
Defined in types.ts:146
Change options for the Panzoom instance
▸ (options?
: PanzoomOptions): void
Parameters:
Name | Type |
---|---|
options? |
PanzoomOptions |
• setStyle: setStyle
Defined in types.ts:148
A convenience method for setting prefixed styles on the Panzoom element
• zoom: function
Defined in types.ts:157
Zoom the Panzoom element to the given scale
panzoom.zoom(2.2)
panzoom.zoom(2.2, { animate: true })
▸ (scale
: number, zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
scale |
number |
zoomOptions? |
ZoomOptions |
• zoomIn: function
Defined in types.ts:168
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 })
▸ (zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
zoomOptions? |
ZoomOptions |
• zoomOut: function
Defined in types.ts:179
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 })
▸ (zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
zoomOptions? |
ZoomOptions |
• zoomToPoint: function
Defined in types.ts:190
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)
▸ (scale
: number, point
: object, zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
▪ scale: number
▪ point: object
Name | Type |
---|---|
clientX |
number |
clientY |
number |
▪Optional
zoomOptions: ZoomOptions
• zoomWithWheel: function
Defined in types.ts:219
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.zoomWithWheel)
// Bind to shift+mousewheel
elem.parentElement.addEventListener('wheel', function(event) {
if (!event.shiftKey) return
panzoom.zoomWithWheel(event)
})
▸ (event
: WheelEvent
, zoomOptions?
: ZoomOptions): CurrentValues
Parameters:
Name | Type |
---|---|
event |
WheelEvent |
zoomOptions? |
ZoomOptions |
• scale: number
Defined in types.ts:113
• x: number
Defined in types.ts:111
• y: number
Defined in types.ts:112
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 }
})
- 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.
Fired when the user starts a move or pinch zoom gesture on mobile.
Fired whenever there is a pan, zoom, or reset. Note that direct calls to options.setTransform
do not fire this event.
Fired whenever the zoom is changed by any Panzoom zoom
method, directly or internally.
Fired whenever the zoom is changed by the pan
method, directly or internally.
Fired when the user finishes a move or finishes a pinch zoom gesture on mobile.
Fired whenever reset is called.