https://github.com/stephanwagner/dompanzoom
https://github.com/stephanwagner/dompanzoom
Last synced: over 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/stephanwagner/dompanzoom
- Owner: StephanWagner
- License: mit
- Created: 2021-09-11T00:25:58.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-04-18T20:11:17.000Z (about 3 years ago)
- Last Synced: 2025-03-02T03:23:05.395Z (over 1 year ago)
- Language: HTML
- Size: 12.3 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# domPanZoom
A lightweight library providing mobile friendly panning and zooming to any HTML DOM element.
---
## Install
### ES6
```bash
npm install dompanzoom --save
```
```javascript
import domPanZoom from 'dompanzoom';
```
### CDN
```html
```
---
## Usage
You need two HTML DOM elements.\
The panZoom element within a wrapper element:
```html
You can add any HTML here
```
Then create a new instance of domPanZoom:
```javascript
new domPanZoom({
wrapperElement: '#my-wrapper',
panZoomElement: '#my-container'
});
```
The options `wrapperElement` and `panZoomElement` are required.\
You can use any query selector or the actual DOM element instance.
> It is highly recommended to give the `panZoomElement` an actual width and height via CSS to avoid size calculation errors due to DOM drawing issues.
---
## 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.
```javascript
new domPanZoom({
wrapperElement: '#my-wrapper',
panZoomElement: '#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, e.g. `.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.
```javascript
var myDomPanZoom = new domPanZoom({
wrapperElement: '#my-wrapper',
panZoomElement: '#my-container'
});
myDomPanZoom.panTo(20, 80);
```
---
## Events
| Event | |
| --- | --- |
| `onInit` | Triggered once domPanZoom is initialized |
| `onChange` | Triggered when panning or zooming |
| `onZoom` | Triggered when zooming |
| `onPan` | Triggered when panning |
### E.g.
```javascript
new domPanZoom({
wrapperElement: '#my-wrapper',
panZoomElement: '#my-container'
onZoom: function (position) {
console.log(this.zoom, position);
}
});
```
---
## Attribution
This library is heavily inspired by https://github.com/anvaka/panzoom.