Panzoom is a progressive plugin to create panning and zooming functionality for an element. Panzoom supports the same browsers as jQuery 2.0 and can be used with jQuery 1.9.0+ or jQuery 2.0+. Rather than setting width and height on an image tag, Panzoom uses CSS transforms and matrix functions 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. And although IE<=8 is not supported, this plugin is future-proof.
jquery.panzoom.min.js (11.2kb/4.2kb gzip), included in this repo, is compressed with uglifyjs.
Download v1.7.0
Development version
For common support questions, see the FAQ at the bottom.
Panzoom includes support for touch gestures and even supports pinch gestures for zooming. It is perfectly suited for both mobile and desktop browsers. You'll be amazed at how well this performs on your mobile device.
iOS and Android are supported.
Also note that devices that support both touch and mouse events at the same time (such as a laptop with a touch screen) are also supported.
Panzoom supports panning and zooming SVG elements directly, in browsers that support SVG.
As of v1.1.0, Panzoom no longer depends on Modernizr for anything. Just jQuery. Before v1.1.0, this plugin depended on Modernizr for its touch support feature detect.
Panzoom can obviously be included with your scripts at the end of the body, but Panzoom supports AMD for javascript module love.
With script tags:
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="/js/plugins/jquery.panzoom.js"></script>
With AMD loader in an anonymous module:
define([ "jquery", "plugins/jquery.panzoom" ], function( $ ) {
$(document).ready(function() {
$(".panzoom-elements").panzoom();
});
});
$(".panzoom-elements").panzoom();
// Pass options
$("a.panzoom-elements").panzoom({
minScale: 0,
$zoomRange: $("input[type='range']")
});
All options can be overridden by passing an object literal like any other plugin,
or with the "option"
method.
Check out the demos of the contain and inverted containment options.
Panzoom.defaults = {
// Should always be non-empty
// Used to bind jQuery events without collisions
// A guid is not added here as different instantiations/versions of panzoom
// on the same element is not supported.
eventNamespace: ".panzoom",
// Whether or not to transition the scale
transition: true,
// Default cursor style for the element
cursor: "move",
// There may be some use cases for zooming without panning or vice versa
// NOTE: disablePan also disables focal point zooming
disablePan: false,
disableZoom: false,
// The increment at which to zoom
// adds/subtracts to the scale each time zoomIn/Out is called
increment: 0.3,
minScale: 0.4,
maxScale: 5,
// The default step for the range input
// Precendence: default < HTML attribute < option setting
rangeStep: 0.05,
// Animation duration (ms)
duration: 200,
// CSS easing used for scale transition
easing: "ease-in-out",
// Indicate that the element should be contained within it's parent when panning
// Note: this does not affect zooming outside of the parent
// Set this value to 'invert' to only allow panning outside of the parent element (basically the opposite of the normal use of contain)
// 'invert' is useful for a large panzoom element where you don't want to show anything behind it
contain: false,
// Transform value to which to always reset (string)
// Defaults to the original transform on the element when panzoom is initialized
startTransform: undefined,
// Zoom buttons/links collection (you can also bind these yourself - e.g. `$button.on("click", function( e ) { e.preventDefault(); $elem.panzooom("zoomIn"); });` )
$zoomIn: $(),
$zoomOut: $(),
// Range input on which to bind zooming functionality
$zoomRange: $(),
// Reset buttons/links collection on which to bind the reset method
$reset: $(),
// For convenience, these options will be bound to panzoom events
// These can all be bound normally on the panzoom element
// e.g. `$elem.on("panzoomend", function( e, panzoom ) { console.log( panzoom.getMatrix() ); });`
onStart: undefined,
onChange: undefined,
onZoom: undefined,
onPan: undefined,
onEnd: undefined,
onReset: undefined
};
Methods can be called in the same way as a widget from the jQuery UI widget factory. Pass a method name when calling panzoom. Strings are interpreted as method names.
// One at a time
// Sets the scale increment option
$elem.panzoom("option", "increment", 0.4);
// Several options at once
$elem.panzoom("option", {
increment: 0.4,
minScale: 0.1,
maxScale: 2,
duration: 500,
$reset: $("a.reset-panzoom, button.reset-panzoom")
});
Any option can be changed. See the defaults above for a list.
Arguments
options
{Object|Boolean}: If a boolean is passed, animate the reset (default: true). If an options object is passed, simply pass that along to setMatrix.options.silent
{Boolean}: Silence the reset event (as well as the change event as the same options are passed to setMatrix)
$elem.panzoom("reset");
$elem.panzoom("reset", false);
$elem.panzoom("reset", {
animate: false,
contain: false
});
Reset the transform matrix to its original value. All panning and zooming is reset.
Arguments
options
{Object|Boolean}: If a boolean is passed, animate the reset (default: true). If an options object is passed, simply pass that along to zoom.
$elem.panzoom("resetZoom");
$elem.panzoom("resetZoom", false);
$elem.panzoom("resetZoom", {
animate: false,
silent: true
});
Reset the scale to its original value (resets both scale values in the matrix to their original values).
Arguments
options
{Object|Boolean}: If a boolean is passed, animate the reset (default: true). If an options object is passed, simply pass that along to pan.
$elem.panzoom("resetPan");
$elem.panzoom("resetPan", false);
$elem.panzoom("resetPan", {
animate: false,
silent: true
});
Reset the pan to its original value.
Arguments
x
{Number}: The translation X value to sety
{Number}: The translation Y value to setoptions
{Object}: These options are also passed along to setMatrix.
1. `options.matrix` _{Array}_: The matrix being manipulated (If this is not passed, the matrix will be calculated on every call to pan, which could be a performance bottleneck if this is bound to a move event)
2. `options.silent` _{Boolean}_: Silence the pan event. Note that this will also silence the setMatrix change event.
3. `options.relative` _{Boolean}_: Make the x and y values relative to the existing matrix.<br/>
e.g. `$elem.panzoom("pan", 10, -10, { relative: true });`<br/>
`// => Moves the element 10 pixels right and 10 pixels up from its current position`
Arguments
scale
{Number|Boolean}: The exact scale to which to zoom or a boolean indicating to transition a zoom outopts
{Object}: All global options can be overwritten by this options object. For example, override the default increment.
1. `opts.noSetRange` _{Boolean}_: Specify that the method should not set the $zoomRange value (as is the case when $zoomRange is calling zoom on change)
2. `opts.animate` _{Boolean}_: Whether to animate the zoom (defaults to true if scale is not a number, false otherwise)
3. `opts.focal` _{jQuery.Event|Object}_: Specify a focal point under which to freeze the zooming element.<br/>
Should either be a jQuery event or an object containing clientX/clientY to specify the point's position relative to the parent.<br/>
For an example of focal point zooming, use the mousewheel or pinch to zoom on the [demo](http://timmywil.github.io/jquery.panzoom/demo/#focal).
4. `opts.silent` _{Boolean}_: Silence the zoom event
5. `opts.dValue` _{Number}_: Think of a transform matrix as four values a, b, c, d<br/>
where a/d are the horizontal/vertical scale values and b/c are the skew values<br/>
(5 and 6 of matrix array are the tx/ty transform values).<br/>
Normally, the scale is set to both the a and d values of the matrix.<br/>
This option allows you to specify a different d value for the zoom.<br/>
For instance, to flip vertically, you could set -1 as the dValue.
// Transition a zoom in based on the scale increment, min and max values
$elem.panzoom("zoom");
// Transition a zoom out
$elem.panzoom("zoom", true);
// Set the scale immediately without a transition
// and silence the zoom event
$elem.panzoom("zoom", 1.2, { silent: true });
Transition a zoom in based on the scale increment, min and max values, and animation duration and easing. This method handles both zooming in and zooming out.
If the method is passed a number, zoom()
will immediately set that scale without transitioning. This is mostly useful for the range input and pinch gestures.
If the method is passed a boolean, true will indicate to perform a zoom-out based on the increment specified in options. If false (or omitted), a zoom-in will be performed.
$elem.panzoom("disable");
Quickly disable panzoom on the element.
$elem.panzoom("enable");
Re-enable panzoom on the element (re-binds all events).
$elem.panzoom("isDisabled");
// => true
Returns a boolean indicating whether the current Panzoom instance is disabled.
Returns a boolean indicating whether the element is currently panning.
$elem.panzoom("destroy");
var panzoom = $elem.panzoom("instance");
Retrieves the Panzoom instance(s) from the set. If there are multiple elements in the set, you will get an array of instances. If there is only one, you will just get that instance of Panzoom.
Unbinds all events and removes all data, including the Panzoom instance on the element.
These methods are basically private, but could be useful under certain circumstances.
Returns the string transform value used by panzoom for the element.
Note: The transform attribute is used for SVG. Otherwise, the appropriately prefixed transform style property is used.
Retrieve an array of values for the specified transform or for the current transform on the panzoom element.
$elem.panzoom("getMatrix");
// => [1, 0, 0, 1, 0, 0]
Arguments
matrix
{Array}: Matrix to setoptions
{Object}
1. `options.animate` _{Boolean}_: If true, a transition will be set to animate the transform change
2. `options.contain` _{Boolean}_: Override the global contain option
3. `options.range` _{Boolean}_: If true, $zoomRange's value will be updated.
4. `options.silent` _{Boolean}_: If true, the change event will not be triggered
// Flip the element upside down
$elem.panzoom("setMatrix", [ 1, 0, 0, -1, 0, 0 ]);
Sets the transform matrix of the panzoom element. It accepts the matrix as an array.
Note: setMatrix()
does not chain. It returns the newly-set matrix as an Array.
$elem.panzoom("transition");
// Turn off transition
$elem.panzoom("transition", true);
// Note: this is different than...
$elem.panzoom("option", "transition", true);
// ... which just sets the `transition` option, indicating whether transitioning is allowed at all.
// If the transition option is false, `$elem.panzoom("transition")` will only ever set transition to "none".
Applies the transition to the element. If off
is true, it removes the transition.
Arguments Received
e
(jQuery.Event): jQuery event objectpanzoom
(Panzoom): The panzoom instanceevent
(jQuery.Event): The starting mousedown or touchstart eventtouches
(TouchList): The touches list if present
Fired when the user starts a move or pinch zoom gesture on mobile.
Arguments Received
e
(jQuery.Event): jQuery event objectpanzoom
(Panzoom): The panzoom instancetransform
(Array): The transform matrix set during the change as an array of values
Fired whenever the matrix is changed by setMatrix()
(whether internally or externally).
Try not to put to much in this event as it could slow down dragging.
Note: This event can be silenced when setMatrix is called directly.
Arguments Received
e
(jQuery.Event): jQuery event objectpanzoom
(Panzoom): The panzoom instancescale
(Number): The zoom scale set by the pluginopts
(Object): Same options passed to zoom
Fired whenever the zoom is changed by this plugin.
Note: This event can be silenced when zoom is called directly.
Arguments Received
e
(jQuery.Event): jQuery event objectpanzoom
(Panzoom): The panzoom instancex
(Number): Translate x valuey
(Number): Translate y value
Fired whenever the pan is changed by this plugin.
Try not to put to much in this event as it could slow down dragging.
Arguments Received
e
(jQuery.Event): jQuery event objectpanzoom
(Panzoom): The panzoom instancematrix
(Array): The final transform matrixchanged
(Boolean): Whether the matrix changed during the panzoom event
This event is fired when the user finishes a move or finishes a pinch zoom gesture on mobile.
Note: When binding to this event, you can tell the difference between a click (or tap) and a move by checking changed
:
$panzoom.on('panzoomend', function(e, panzoom, matrix, changed) {
if (changed) {
// deal with drags or touch moves
} else {
// deal with clicks or taps
}
});
Arguments Received
e
(jQuery.Event): jQuery event objectpanzoom
(Panzoom): The panzoom instancematrix
(Array): The original matrix
Fired whenever reset is called.
Tests can be run by opening test/index.html in a browser or by using grunt
and phantomjs.
Tests are written with mocha and chai for bdd-style assertions.
See CONTRIBUTING.md for more info.
- How do I make it so that I never see the background behind the panzoom element? example
- This can be done with the
contain
option. Setcontain
to"invert"
and make sure the panzoom element is the same size or larger than its parent.