domPanZoom

Add mobile friendly panning and zooming to any HTML DOM element.

Install

ES6

npm install --save dompanzoom

import domPanZoom from 'dompanzoom';

CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/domPanZoom.min.js"></script>

Usage

You need two HTML DOM elements. The panZoom element within a wrapper element:

<div id="my-wrapper">
  <div id="my-container">
    <p>You can add any HTML here<p>
  </div>
</div>

Then create a new instance of domPanZoom:

new domPanZoom({
  // The ID of the wrapper element (required)
  wrapperElementID: 'my-wrapper',

  // The ID of the container element (required)
  panZoomElementID: 'my-container'
});

Options

You can pass the following options into domPanZoom:

| Option | Default | | | --- | --- | --- | | center | true | Start with a centered position. This option overrides initalPanX and initialPanY | | bounds | cover | Set this option to 'contain' or 'cover' to limit the boundries of the panZoomElement to the wrapperElement. This works similar to the CSS property background-size: contain / cover. Setting this option might effect the option minZoom | | minZoom | 0.1 | Minimum zoom, 0.5 would be half the original size | | maxZoom | 10 | Maximum zoom, 2 would be double the original size | | panStep | 10 | How many percent to pan by default with the panning methods panLeft, panRight, panUp and panDown | | zoomStep | 50 | How many percent to zoom by default with the methods zoomIn and zoomOut | | zoomWheelSpeed | 1 | The speed in which to zoom when using the mouse wheel | | initialZoom | 1 | Initial zoom level | | initialPanX | 0 | Initial horizontal pan in percent | | initialPanY | 0 | Initial vertical pan in percent | | transitionSpeed | 400 | Transition speed in milliseconds, higher values are slower |

E.g.

new domPanZoom({
  wrapperElementID: 'my-wrapper',
  panZoomElementID: 'my-container',
  bounds: false,
  minZoom: 1
});

Methods

You can use the following methods:

| Getters | | | --- | --- | | .getPan() | Returns an object with X and Y values of current pan position. You can pass true to get the actual pixel values, e.g. .getPan(true) | | .getPanX() | Returns the current horizontal position. You can pass true to get the actual pixel values, e.g. .getPanX(true) | | .getPanY() | Returns the current vertical position. You can pass true to get the actual pixel values, e.g. .getPanY(true) | | .getZoom() | Returns the current zoom level |

| Setters | | | --- | --- | | .panLeft().panRight().panUp().panDown() | Pan a specific direction. You can pass a number to pan a specific amount (in percent). Pass true as first or second argument to pan instantly, e.g. .panLeft(50), .panRight(true), .panUp(30, true) | | .panTo(x, y) | Pan to a specific position. The x and y values are in percent, so .panTo(50, 50) will pan to the center. Pass true as third argument to pan instantly, e.g. .panTo(50, 50, true) | .center() | Pan to centered position. Pass true to center instantly, e.g. .center(true) | | .zoomIn().zoomOut() | Zoom in and out. You can pass a number to zoom a specific amount (in percent). Pass true as first or second argument to zoom instantly, .zoomIn(20), .zoomIn(true), .zoomIn(50, true) | | .zoomTo(2) | Zoom to a specific zoom level. Pass true as a second argument to zoom instantly, e.g. .zoomTo(2, true) |

E.g.

var myDomPanZoom = new domPanZoom({
  wrapperElementID: 'my-wrapper',
  panZoomElementID: 'my-container'
});

myDomPanZoom.panTo(20, 80);

Events

| Event | | | --- | --- | | onInit | Triggered once domPanZoom is initialized | | onChange | Triggered while panning or zooming | | onZoom | Triggered while zooming | | onPan | Triggered while panning |

E.g.

var myDomPanZoom = new domPanZoom({
  wrapperElementID: 'my-wrapper',
  panZoomElementID: 'my-container',

  onZoom: function () {
    console.log(this.getZoom());
  }
});

Attribution

This library is heavily inspired by https://github.com/anvaka/panzoom.