Registry / web-framework / vue-pinch-zoom

vue-pinch-zoom

library1.0.1jsnpmunverified

vue-pinch-zoom is a specialized Vue.js component designed to provide pinch-zoom and drag functionalities for images using touch gestures. It allows users to scale and pan image content within a defined container, offering features like configurable transition durations, zoom limits (absolute or based on original image size), minimum scale settings, and automatic zoom-out. It supports both double-tap and mouse wheel interactions, and includes options to disable panning, customize zoom controls, and handle container overflow. As of version 1.0.1, the library's `peerDependencies` indicate support for both Vue 2 (`^2.5.0`) and Vue 3 (`^3.0.0`), although its installation and usage examples in the README primarily demonstrate Vue 2 global registration syntax. The library ships with TypeScript types, enhancing developer experience in TypeScript projects. It differentiates itself by offering a comprehensive set of properties for fine-grained control over the zoom and pan behavior, catering to various use cases from simple image viewers to more interactive applications. The release cadence is not explicitly stated but appears to be stable at its current version.

web-framework

npm install vue-pinch-zoom

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-PINCH-ZOOM

vue-pinch-zoom

web-frameworkjavascriptv1.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PinchZoom (for global registration)

✓ import PinchZoom from 'vue-pinch-zoom'; Vue.component('pinch-zoom', PinchZoom);

✗ const PinchZoom = require('vue-pinch-zoom'); // CommonJS is typically not preferred for Vue components

This example assumes a global Vue instance (Vue 2 context) for component registration. For Vue 3, you would typically use `app.component('pinch-zoom', PinchZoom)` after creating your Vue app instance.

PinchZoom (for local registration)

✓ import PinchZoom from 'vue-pinch-zoom'; export default { components: { PinchZoom }, // ... };

✗ import { PinchZoom } from 'vue-pinch-zoom'; // Incorrect named import for the default export

This is the standard way to register components locally within a Vue Single File Component (SFC) for both Vue 2 and Vue 3, assuming PinchZoom is a default export.

PinchZoomProps (TypeScript types)

✓ import PinchZoom, { PinchZoomProps } from 'vue-pinch-zoom'; // Use PinchZoomProps for component props type definitions, e.g., in an interface or type alias

✗ import { PinchZoom } from 'vue-pinch-zoom'; // Incorrect for the component itself, correct for a named type

The library ships with TypeScript types, allowing for type checking of properties and methods when working in a TypeScript project. `PinchZoomProps` is an interface describing the component's available properties.

Demonstrates installation, global component registration (Vue 2 style), and basic usage of the pinch-zoom component with an image, showcasing common properties like `limitZoom`, `autoZoomOut`, and `doubleTap`.

npm i vue-pinch-zoom // main.js (or similar entry point for a Vue 2 application) import Vue from 'vue'; import PinchZoom from 'vue-pinch-zoom'; // Globally register the component for use across your application Vue.component('pinch-zoom', PinchZoom); // Create a basic Vue app instance new Vue({ el: '#app', template: ` <div id="app" style="width: 100%; height: 400px; border: 1px solid #ccc; display: flex; justify-content: center; align-items: center; overflow: hidden;"> <pinch-zoom :limitZoom="2.5" :autoZoomOut="true" :doubleTap="true" :minScale="0.5" :backgroundColor="'rgba(0,0,0,0.5)'" > <img src="https://picsum.photos/id/1018/800/600" alt="Forest by a lake" style="max-width: 100%; max-height: 100%; object-fit: contain;" /> </pinch-zoom> </div> ` });

Debug

Known issues

gotchaWhile `vue-pinch-zoom` officially supports both Vue 2 (`^2.5.0`) and Vue 3 (`^3.0.0`), the quickstart and README examples primarily use Vue 2 syntax (`Vue.component`). Developers integrating into Vue 3 projects need to use the `app.component` method for global registration or import and register locally within `<script setup>` or the `components` option.

fix

For Vue 3, use `app.component('pinch-zoom', PinchZoom)` in your `main.ts` or `main.js` file for global registration. For local usage, simply import `PinchZoom` and add it to the `components` option of your SFC (or use directly in `<script setup>`).

affects: >=1.0.0

gotchaThe `limitZoom` property accepts both a `number` (e.g., `2.5`) and the specific string literal `"original image size"`. Providing any other string or an incorrect type will lead to unexpected behavior or runtime errors.

fix

Ensure `limitZoom` is either a numeric value or precisely the string `"original image size"`. When using TypeScript, the `PinchZoomProps` interface will guide correct usage.

affects: >=1.0.0

gotchaWhen the `autoHeight` property is set to `true`, the component expects the `<img>` tag inside to have explicit `width` and `height` attributes to correctly calculate the container's initial dimensions. Without these, there may be a delay or incorrect sizing of the container.

fix

If `autoHeight` is `true`, always provide `width` and `height` attributes to the `<img>` tag within the `<pinch-zoom>` component: e.g., `<img src="..." width="800" height="600" />`.

affects: >=1.0.0

gotchaThe `listeners` property has an `"auto"` option which subscribes only to touch or mouse events based on the detected screen type. If you need both touch and mouse interactions to be active on all devices (e.g., hybrid laptops or debugging in a browser with touch simulation), explicitly set it to `"mouse and touch"`.

fix

To ensure both mouse and touch events are always handled, set the prop as `:listeners="'mouse and touch'"`.

affects: >=1.0.0

gotchaThe `pinch-zoom` component requires its container (or a parent element) to have defined dimensions (width and height) to function correctly. If the container has an undefined height, the component might not render or behave as expected with respect to scaling and panning boundaries.

fix

Ensure the `<pinch-zoom>` wrapper or its direct parent has explicit `width` and `height` CSS properties, for example: `style="width: 100%; height: 400px;"` or using CSS classes.

affects: >=1.0.0

Errors

Common errors & fixes

[Vue warn]: Unknown custom element: <pinch-zoom> - did you register the component correctly?

The `pinch-zoom` component was not properly registered either globally or locally within your Vue application before being used in a template.

fix

For global registration (Vue 2): `Vue.component('pinch-zoom', PinchZoom);`. For global registration (Vue 3): `app.component('pinch-zoom', PinchZoom);`. For local registration (Vue 2/3): include `PinchZoom` in the `components` option of your parent component: `components: { PinchZoom }`.

Property 'limitZoom' does not exist on type 'PinchZoomProps'.

This TypeScript error indicates that an incorrect type or value was passed to the `limitZoom` prop, or that the property name itself is misspelled. The prop expects either a `number` or the string literal `"original image size"`.

fix

Ensure the value for `limitZoom` matches its expected types, e.g., `:limitZoom="2.5"` or `:limitZoom="'original image size'"`. Double-check the prop name for typos.

TypeError: Cannot read properties of undefined (reading 'component')

This runtime error typically occurs in Vue 2 setups when attempting to use `Vue.component` without a globally available `Vue` instance, often in modular environments where Vue is imported but not explicitly exposed globally.

fix

If using a build tool with Vue 2, ensure Vue is imported and instantiated (e.g., `new Vue({...})`). For Vue 3, this error is less common as global app registration uses an `app` instance (`app.component`). Ensure your setup correctly initializes Vue.

[Vue warn]: Invalid prop: type check failed for prop "limitZoom". Expected Number, String with value "original image size", got String with value "invalid-string".

The `limitZoom` property received a string value that is neither a number nor the precise literal `"original image size"`, violating its prop type validation.

fix

Correct the value of the `limitZoom` prop to either a valid number (e.g., `:limitZoom="2.0"`) or the exact string `"original image size"` (e.g., `:limitZoom="'original image size'"`). Review the property documentation carefully.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

vuerequiredRequired as a peer dependency for the Vue component to function. Supports both Vue 2 and Vue 3.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/drozhzhin-n-e/vue-pinch-zoom ↗

packagehttps://www.npmjs.com/package/vue-pinch-zoom ↗

homepagehttp://ivylab.space/pinch-zoom/vue ↗