svg-pan-zoom

By default, the library uses the top-level <g> element as the viewport. To pan/zoom only a specific layer, assign the class svg-pan-zoom_viewport to that SVGGElement.

Important: Do not set any transform attributes directly on the element with the svg-pan-zoom_viewport class. If you need a transform, wrap it in a nested group:

<g class="svg-pan-zoom_viewport">
  <g transform="matrix(1,0,0,1,0,0);"></g>
</g>

You can also specify the viewport via the viewportSelector option in the configuration.

svgPanZoom('#demo-tiger', {
  viewportSelector: '.svg-pan-zoom_viewport'
});

If you are using <embed> or <object> elements to load remote SVGs, or if you render the SVG after the page has loaded, you must wait for the SVG to be loaded before calling svgPanZoom. You can do this by listening to the load event on the element.

<embed type="image/svg+xml" src="/path/to/my/file.svg" id="my-embed"/>

<script>
document.getElementById('my-embed').addEventListener('load', function(){
  // Will get called after embed element was loaded
  svgPanZoom(document.getElementById('my-embed'));
})
</script>

To use the library, reference the svg-pan-zoom.js file in your HTML. You can initialize pan and zoom behavior by calling the svgPanZoom function with either a CSS selector of an SVG element or the DOM element itself.

var panZoomTiger = svgPanZoom('#demo-tiger');
// or
var svgElement = document.querySelector('#demo-tiger')
var panZoomTiger = svgPanZoom(svgElement)

You can add custom event support (like pinch or double tap) using the customEventsHandler option. This requires providing haltEventListeners (to prevent conflicts with default touch events), an init function, and a destroy function.

var options = {
  zoomEnabled: true
, controlIconsEnabled: true
, customEventsHandler: {
    // Halt all touch events
    haltEventListeners: ['touchstart', 'touchend', 'touchmove', 'touchleave', 'touchcancel']

    // Init custom events handler
  , init: function(options) {
      // Init Hammer
      this.hammer = Hammer(options.svgElement)

      // Handle double tap
      this.hammer.on('doubletap', function(ev){
        options.instance.zoomIn()
      })
    }

    // Destroy custom events handler
  , destroy: function(){
      this.hammer.destroy()
    }
  }
}

svgPanZoom('#mobile-svg', options);

SVG height is broken

Because the library removes the viewBox attribute, the SVG height might default to a small value (e.g., 150px). Fix: Explicitly set a height on the SVG or its object/embed container.

Errors when SVG is hidden

The library does not support working with SVGs that are hidden (e.g., display: none), as browsers may detach child documents from the DOM when they are hidden.

Performance issues

• Initialization: If initialization is slow, wrap all child elements in a single <g> element beforehand to prevent the library from having to move them.
• Panning/Zooming: Slow performance is usually caused by very large SVG files that the browser cannot render quickly enough.

If you modify the contents of the SVG (the viewport) such that the bounding box of all elements changes, you must call updateBBox() so that fit() and other calculations work correctly.

var panZoomTiger = svgPanZoom('#demo-tiger');
panZoomTiger.fit();

// Update SVG rectangle width
document.getElementById('demo-tiger').querySelector('rect').setAttribute('width', 200)

// fit does not work right anymore as viewport bounding box changed
panZoomTiger.fit();

panZoomTiger.updateBBox(); // Update viewport bounding box
panZoomTiger.fit(); // fit works as expected

Call getSizes() to retrieve an object containing the current state of the SVG:

• width: Cached SVG width.
• height: Cached SVG height.
• realZoom: The a and d attributes of the transform matrix applied over the viewport.
• viewBox: An object containing width, height, x, and y of the viewport bounding box.

You can add on-screen zoom controls (Zoom In, Reset, and Zoom Out) to your svg-pan-zoom instance by calling the enable method from the control icons module. This method injects SVG elements into your SVG container, including a <style> block for styling the controls. The controls are positioned relative to the SVG's width and height.

Note that the enable method attaches the created control group to the instance.controlIcons property, allowing you to reference them later.