vue-zoomable

Tiny and high performance zoom and pan library for Vue 3. It uses CSS Transforms which provides hardware acceleration.

Checkout the demos.

Installation

npm install vue-zoomable

Usage

Immediate child of VueZoomable must be either svg or an html container.

<template>
  <VueZoomable
    style="width: 500px; height: 500px; border: 1px solid black"
    selector="#myContent"
    :minZoom="0.5"
    :maxZoom="3"
  >
    <svg>
      <g id="myContent">
        <circle x="10" y="10" r="50" />
      </g>
    </svg>
  </VueZoomable>
</template>

<script setup lang="ts">
import VueZoomable from "vue-zoomable";
import "vue-zoomable/dist/style.css";
</script>

Model

• v-model:zoom
• v-model:pan

Props

Name	type	default	Description
selector	string	* > *	Root element to apply transform on. Preferrably an id on <div> or <g> tag
maxZoom	number	3	Maximum allowed zoom
minZoom	number	0.5	Minimum allowed zoom
dblClickZoomStep	number	0.4	Step size for zoom on double click
wheelZoomStep	number	0.05	Step size for zoom on wheel
panEnabled	boolean	true	Enable panning
zoomEnabled	boolean	true	Enable zoom
mouseEnabled	boolean	true	Enable mouse events
touchEnabled	boolean	true	Enable touch events
dblClickEnabled	boolean	true	Zoom on double click enabled
wheelEnabled	boolean	true	Zoom on mouse enabled
initialZoom	number	0.5	(Deprecated) Initial zoom value. Use v-model:zoom
initialPanX	number	0	(Deprecated) Initial pan along x-axis. Use v-model:pan
initialPanY	number	0	(Deprecated) Initial pan along y-axis. Use v-model:pan
enableControllButton	boolean	false	Defines, if the controll buttons will be enabled.
buttonPanStep	number	15	Step size for pan on controll buttons
buttonZoomStep	number	0.1	Step size for pan on controll buttons
enableWheelOnKey	string	undefined	If not null, the wheel is disabled, until the corresponding Key is pressed. You can set it to any value of event.key. see here

Document Flow

If you have any document flow whatsoever on your page, it certainly won't do if you can only zoom with the mouse wheel. Because that would scroll the document at the same time. Thanks to Hellow2 for document flow and control buttons features.

---

My sollution was inspired by Google-Maps. You can set the prop enableWheelOnKey to whatever key button you like. (Every value that can be found in KeyEvents event.key are valid and should work). If enableWheelOnKey is set, the zoom on Wheel will only work, if simmultaniously the corresponding Button is pressed.

If you have a document flow, it is reccomended, to set enableWheelOnKey to the value Control.

<VueZoomable :enableWheelOnKey="'Control'">
</VueZoomable>

Now usually Control + wheel zooms in and out of the viewport. This... isn't good. Arguably this is a worse ux as scrolling while zooming. That's why I prevent it when following cases are all met:

• enableWheelOnKey is set to "Control"
• the mouse is within the bounds of the container element
• you... well would zoom the viewport

Because this could be unintuitive, I implemented a message that tells you what you need to do to actually zoom, that appears after you would have zoomed without this. Just like Google did.

---

Events

• panned
• zoom

All events have argument of type ZoomableEvent.

ZoomableEvent

Field	Type	Description
zoom	number	Current zoom value
pan	object	Current pan value and delta change in case of panned event.
type	string	Source type which triggered the event. dblClick, mouse, touch or wheel.

Sample event data:

{
  "zoom": 0.3,
  "pan": {
    "x": 100,
    "y": 2,
    "deltaX": 0,
    "deltaY": 2
  },
  "type": "mouse"
}

Contribute

Contributions are most welcome. Please follow the below steps for any contributions.

If you add new feature

• Open a suggestion issue first.
• Provide your reasoning on why you want to add this feature.
• Submit your PR.

If you fix a bug

• If you are resolving an issue, please add fix: #<issue number> <short message> in your PR title (e.g.fix: #3899 update entities encoding/decoding).
• Provide a description of the bug in your PR and/or link to the issue.

Setup

The setup is pretty easy. You need to have pnpm installed.

# install the dependencies
pnpm i

# start the dev thingie
pnpm run dev

Where should I start?

A good way to start is to find an issue labeled as bug, help wanted or feature request and suggest your approach in comments.

Other ways to help:

• Write tests
• Documentation & Demos
• Share your thoughts! Any features you thing vue-zoomable is missing? Any suggestions? Would love to hear that.

Acknowledgements

• @panzoom/panzoom