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