jquery-svg-pan-zoom

jQuery plugin to enable pan and zoom in SVG images either programmatically or through mouse/touch events.

Features

Programmatically manipulate the SVG viewBox
Mouse and touch events to pan the SVG viewBox
Mousewheel events to zoom in or out the SVG viewBox
Animations
Mousewheel zooming keeps the cursor over the same coordinates relative to the image (A.K.A. GoogleMaps-like zoom)
Limiting the navigable area

Requirements

jQuery

SVG-enabled browser (does not work with SVG work-arounds that use Flash)

The viewBox

The viewBox is an attribute of SVG images that defines the area of the SVG that is visible, it is defined by 4 numbers: X, Y, Width, Height. These numbers together specify the visible area. This plugin works by manipulating these four numbers. For example, moving the image to the right alters the X value while zooming in reduces Width and Height.

Usage

var svgPanZoom= $("svg").svgPanZoom(options)

If the selection has more than one element svgPanZoom will return an array with a SvgPanZoom object for each image in the same order of the selection. If only one element is selected then the return is a single SvgPanZoom object. If no elements are selected the above call returns null

The returned SvgPanZoom object contains all options, these options can be overriden at any time directly, for example to disable mouseWheel events simply:

svgPanZoom.events.mouseWheel= false

the SvgPanZoom object also has methods for manipulating the viewBox programmatically. For example:

svgPanZoom.zoomIn()

will zoomIn the image using options.zoomFactor.

Building

This project requires coffeescript to be installed in order to build.

coffee -m --compile --output compiled/ src/

Options

Options:
{
    events: {
        mouseWheel: boolean (true), // enables mouse wheel zooming events
        doubleClick: boolean (true), // enables double-click to zoom-in events
        drag: boolean (true), // enables drag and drop to move the SVG events
        dragCursor: string "move" // cursor to use while dragging the SVG
    },
    animationTime: number (300), // time in milliseconds to use as default for animations. Set 0 to remove the animation
    zoomFactor: number (0.25), // how much to zoom-in or zoom-out
    maxZoom: number (3), //maximum zoom in, must be a number bigger than 1
    panFactor: (number (100), // how much to move the viewBox when calling .panDirection() methods
    initialViewBox: { // the initial viewBox, if null or undefined will try to use the viewBox set in the svg tag. Also accepts string in the format "X Y Width Height"
        x: number (0) // the top-left corner X coordinate
        y: number (0) // the top-left corner Y coordinate
        width: number (1000) // the width of the viewBox
        height: number (1000) // the height of the viewBox
    },
    limits: { // the limits in which the image can be moved. If null or undefined will use the initialViewBox plus 15% in each direction
        x: number (-150)
        y: number (-150)
        x2: number (1150)
        y2: number (1150)
    }
}

Methods

svgPanZoom.panLeft(amount, animationTime)
svgPanZoom.panRight(amount, animationTime)
svgPanZoom.panUp(amount, animationTime)
svgPanZoom.panDown(amount, animationTime)

Moves the SVG viewBox in the specified direction. Parameters:

amount: Number, optional. How much to move the viewBox, defaults to options.panFactor.
animationTime: Number, optional. How long the animation should last, defaults to options.animationTime.
zoom

svgPanZoom.zoomIn(animationTime)
svgPanZoom.zoomOut(animationTime)

Zooms the viewBox. Parameters:

animationTime: Number, optional. How long the animation should last, defaults to options.animationTime.
reset

svgPanZoom.reset()

Resets the SVG to options.initialViewBox values.

getViewBox

svgPanZoom.getViewBox()

Returns the viewbox in this format:

{
    x: number
    y: number
    width: number
    height: number
}

setViewBox

svgPanZoom.setViewBox(x, y, width, height, animationTime)

Changes the viewBox to the specified coordinates. Will respect the options.limits adapting the viewBox if needed (moving or reducing it to fit into options.limits

x: Number, the new x coodinate of the top-left corner
y: Number, the new y coodinate of the top-left corner
width: Number, the new width of the viewBox
height: Number, the new height of the viewBox
animationTime: Number, optional. How long the animation should last, defaults to options.animationTime.
setCenter

svgPanZoom.setCenter(x, y, animationTime)

Sets the center of the SVG. Parameters:

x: Number, the new x coordinate of the center
y: Number, the new y coordinate of the center
animationTime: Number, optional. How long the animation should last, defaults to options.animationTime.

Notes:

Only works in SVGs inlined in the HTML. You can use $.load() to load the SVG image in the page using AJAX and call $().svgPanZoom() in the callback
Touch pinch events to zoom not yet supported
This plugin does not create any controls (like arrows to move the image) on top of the SVG. These controls are simple to create manually and they can call the methods to move the image.
Do not manipulate the SVG viewBox attribute manually, use SvgPanZoom.setViewBox() instead

leerlemoniii/jquery-svg-pan-zoom