Vue Pan and Zoom Component

1.1.6 · active · verified Sun Apr 19

The `vue-panzoom` library is a Vue.js plugin that provides intuitive pan and zoom capabilities for various DOM elements, including images, regular HTML content, and SVG. It serves as a Vue.js wrapper around the well-regarded `anvaka/panzoom` JavaScript library, inheriting its robust features and mobile-friendly design. The current stable version, 1.1.6, offers flexibility through attributes like `selector` to target specific elements within the component's scope and supports all options provided by the underlying `panzoom` library. Developers can also customize the component's name and listen to a comprehensive set of events, including its own `init` event and all `panzoom` lifecycle events, allowing for fine-grained control over the pan and zoom experience. While a strict release cadence isn't specified, the recent updates addressing Vue 3 compatibility (starting from v1.1.4) indicate active maintenance and adaptation to the Vue ecosystem's evolution. Its primary differentiator is its seamless integration into Vue applications, abstracting the complexities of direct `panzoom` library usage while exposing its full power.

Common errors

```
Error in main.js: "Failed to mount app: mount must be called on an element that is not already mounted."
```
cause This error often indicates an incompatibility between the Vue version used in your project and the `vue-panzoom` package. Specifically, using `vue-panzoom` versions 1.1.4 or higher with a Vue 2 project.

fix If your project uses Vue 2, you must install `vue-panzoom@1.1.3` to ensure compatibility: `npm install vue-panzoom@1.1.3`. If using Vue 3, verify your Vue setup is correct.
```
[Vue warn]: Unknown custom element: <panZoom> - did you register the component correctly?
```
cause The `vue-panzoom` component was not properly registered as a Vue plugin before being used in a template. This can happen if `Vue.use(panZoom)` is omitted or called after the Vue app is mounted.

fix Ensure that `import panZoom from 'vue-panzoom'; Vue.use(panZoom);` is present and executed in your main application entry point (e.g., `main.js`) before your Vue application instance is created and mounted. Also, verify that if a custom component name was provided during installation (e.g., `Vue.use(panZoom, { componentName: 'MyZoom' })`), you are using that custom name (`<MyZoom>`) in your templates.

Warnings

breaking Version 1.1.4 and later of `vue-panzoom` introduced a breaking change by switching to `rollup-plugin-vue` version 6+, which requires Vue 3. Projects using Vue 2 must use an older version.
Fix: For Vue 2 projects, downgrade your `vue-panzoom` dependency to version 1.1.3: `npm install vue-panzoom@1.1.3`. For Vue 3 projects, ensure Vue 3 is correctly installed in your project.

Install

npm install vue-panzoom npm
yarn add vue-panzoom yarn
pnpm add vue-panzoom pnpm

Imports

panZoom
wrong:
```
const panZoom = require('vue-panzoom')
```
correct:
```
import panZoom from 'vue-panzoom'
```
This is the default export used to install the plugin via `Vue.use()`.
Vue.use
```
import panZoom from 'vue-panzoom'; Vue.use(panZoom);
```
Registers the pan-zoom component globally for use in templates. An optional `componentName` can be passed as a second argument to customize the tag name.
PanZoom component
```
<panZoom></panZoom>
```
This is the default component tag used in Vue templates after `Vue.use(panZoom)` has been called. If a `componentName` option was provided during installation, use that custom name instead.

Quickstart

Demonstrates global plugin installation with a custom component name, and basic usage within a Vue template showcasing pan/zoom on both DOM images and SVG elements, including custom options and event handling.

import Vue from 'vue'
import App from './App.vue'
import panZoom from 'vue-panzoom'

// Install plugin, optionally change component name
Vue.use(panZoom, { componentName: 'MyPanZoomComponent' });

new Vue({
  render: h => h(App),
}).$mount('#app');

// Example App.vue content:
/*
<template>
    <div id="app">
        <!-- Apply to an image with custom options and event listener -->
        <MyPanZoomComponent :options="{minZoom: 0.5, maxZoom: 5}" @panstart="onPanStart">
            <img src="https://picsum.photos/300">
        </MyPanZoomComponent>

        <!-- Apply to SVG with a specific selector -->
        <MyPanZoomComponent selector="#svg-target" @init="onInit">
            <svg height="210" width="400">
                <g id="svg-target">
                    <path d="M150 0 L75 200 L225 200 Z" />
                </g>
            </svg>
        </MyPanZoomComponent>
    </div>
</template>

<script>
export default {
  methods: {
    onPanStart(e) {
      console.log('Pan started:', e);
    },
    onInit(panzoomInstance, id) {
      console.log('Panzoom initialized for ID:', id);
      panzoomInstance.on('zoom', (e) => {
        console.log('Zoom event via instance:', e);
      });
    }
  }
}
</script>
*/

view raw JSON →