Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/frameable/tragopan

Minimal dependency-free pan/zoom library
https://github.com/frameable/tragopan

Last synced: 21 days ago
JSON representation

Minimal dependency-free pan/zoom library

Awesome Lists containing this project

README 

        
![](https://team-video.github.io/tragopan/mascot.jpg)



# tragopan



Minimal dependency-free pan/zoom library



```html

  


    


      

    


  



  

    const tragopan = new Tragopan({

      viewport: document.querySelector('#viewport'),

      content: document.querySelector('#content')

    });

  

```



## Features



- Vanilla JavaScript

- Just ~200 source lines of code

- Minified gzip'd payload is about 1.6k

- Fast -- uses native browser scrolling for panning

- Focal zooming in/out based on mouse pointer position

- Options for panning with space-drag, zooming with scroll

- Made with :heart: at https://frameable.com



## How it works



Tragopan uses native browser scrolling as its implementation for panning (left/right/up/down), and transform/scale for zooming (in/out).  In our testing, we found that native scrolling was far more efficient than using transform for panning.  As an extra bonus, if your DOM is structured so that your `viewport` element can be your document body, some browsers appear to do even more optimization for that special case.



## Methods



### new Tragopan(options)



Instantiate a pan/zoomable tragopan instance, given a viewport and a nested content element.  Options include:



  - `viewport`: reference to a top-level element which will contain content to be panned and zoomed

  - `content`: a child element of the viewport

  - `scaleIncrement`: percentage by which zooming in or out one click should change the scale (default `0.04`)

  - `scrollZoom`: enable bare scrolling to zoom, rather than ctrl/option-scroll to zoom (default `false`)

  - `spacePan`: enable panning via holding down the space bar (default `false`)

  - `minScale`: minimum zoom scale factor (default `0.5`)

  - `maxScale`: maximum zoom scale factor (default `4`)



### tragopan.configure(options)



Configure a tragopan instance with any options accepted by the constructor above.



### tragopan.pan(x, y)



Pan to the given x and y coordinates in content space.



### tragopan.zoom(scale[, focalPoint])



Zoom to the given scale, keeping the given focal point in-place on the screen.  Focal point should be an object with x and y coordinates in content space.  If focal point is ommitted, the center point of the viewport is used instead.



### tragopan.zoomIn([scaleIncrement])



Zoom in by the given `scaleIncrement` if provided, or else zoom in by the configured/default `scaleIncrement`.



### tragopan.zoomOut([scaleIncrement])



Zoom out by the given `scaleIncrement` if provided, or else zoom out by the configured/default `scaleIncrement`.



### tragopan.center()



Pan to the center of the content



### tragopan.reset()



Pan to the center of the content



### tragopan.on(eventName, handlerFn)



Register an event handler to be called when some panning or zooming event occurs.  See below for more info.



## Events



### panstart



Fired when a pan may be starting as a result of the user mousing-down on the viewport.  A pan may or may not follow, with a click being a possible alternative conclusion.



### panmove



Fired when the content moves relative to the viewport, whether from a click-drag, from a call to `zoom()`, or from a native scroll mouse event.



### panend



Fired when a pan via click-drag ends with a mouse-up.



### panzoom



Fired when the scale changes, either from a call to `zoom()`, or from a native 

ctrl/option-scroll mouse event.



### panchange



Fired when any event above occurs.