vue-zoomable

Introduction

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

Checkout the demos.

Features

• Simply wrap your content in VueZoomable component to make it zoom-able and pan-able.
• Mouse wheel support
• Touch and pinch-zoom support
• Control buttons for zoom and pan
• Supports SVG and HTML content
• Uses CSS transform for zoom and pan
• ScrollOverlay component to lock pan/zoom while scrolling

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>

API Reference

VueZoomable

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.2	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
enableControlButton	boolean	true	Enable or disable control buttons
buttonPanStep	number	15	Step size for pan on control buttons
buttonZoomStep	number	0.1	Step size for pan on control buttons
zoomOrigin	string	content-center	Possible values, content-center: Scale the content w.r.t its center center: Scale the content w.r.t center of the container pointer: Scale the content w.r.t position of the pointer

Model

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

Slots

• default - Default Content
• buttons - Control buttons

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, wheel or control-btn.

Sample event data:

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

ScrollOverlay

Prevents mistaken zoom/pan while scrolling the page using mouse wheel or touchscreen. Useful if your zoomable content is embedded within scrollable content. Google map provides similar functionality Google.

Props

Name	type	default	Description
wheelUnlockKey	string	Control	Wheel is disabled, until the corresponding Key is pressed. You can set it to any value of event.key. see here
enableWheelLock	boolean	true	When true, zoom using wheel is disabled until wheelUnclockKey is pressed.
enableTouchLock	boolean	true	When true, pan or zoom requires touch using two fingers.

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