{"id":14293,"library":"vue-pinch-zoom","title":"Vue Pinch Zoom Component","description":"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.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/drozhzhin-n-e/vue-pinch-zoom","tags":["javascript","Vue","Pinch zoom","Touch image zoom","typescript"],"install":[{"cmd":"npm install vue-pinch-zoom","lang":"bash","label":"npm"},{"cmd":"yarn add vue-pinch-zoom","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-pinch-zoom","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for the Vue component to function. Supports both Vue 2 and Vue 3.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"const PinchZoom = require('vue-pinch-zoom'); // CommonJS is typically not preferred for Vue components","symbol":"PinchZoom (for global registration)","correct":"import PinchZoom from 'vue-pinch-zoom';\nVue.component('pinch-zoom', PinchZoom);"},{"note":"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.","wrong":"import { PinchZoom } from 'vue-pinch-zoom'; // Incorrect named import for the default export","symbol":"PinchZoom (for local registration)","correct":"import PinchZoom from 'vue-pinch-zoom';\n\nexport default {\n  components: {\n    PinchZoom\n  },\n  // ...\n};"},{"note":"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.","wrong":"import { PinchZoom } from 'vue-pinch-zoom'; // Incorrect for the component itself, correct for a named type","symbol":"PinchZoomProps (TypeScript types)","correct":"import PinchZoom, { PinchZoomProps } from 'vue-pinch-zoom';\n// Use PinchZoomProps for component props type definitions, e.g., in an interface or type alias"}],"quickstart":{"code":"npm i vue-pinch-zoom\n\n// main.js (or similar entry point for a Vue 2 application)\nimport Vue from 'vue';\nimport PinchZoom from 'vue-pinch-zoom';\n\n// Globally register the component for use across your application\nVue.component('pinch-zoom', PinchZoom);\n\n// Create a basic Vue app instance\nnew Vue({\n  el: '#app',\n  template: `\n    <div id=\"app\" style=\"width: 100%; height: 400px; border: 1px solid #ccc; display: flex; justify-content: center; align-items: center; overflow: hidden;\">\n      <pinch-zoom\n        :limitZoom=\"2.5\"\n        :autoZoomOut=\"true\"\n        :doubleTap=\"true\"\n        :minScale=\"0.5\"\n        :backgroundColor=\"'rgba(0,0,0,0.5)'\"\n      >\n        <img src=\"https://picsum.photos/id/1018/800/600\" alt=\"Forest by a lake\" style=\"max-width: 100%; max-height: 100%; object-fit: contain;\" />\n      </pinch-zoom>\n    </div>\n  `\n});","lang":"javascript","description":"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`."},"warnings":[{"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>`).","message":"While `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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\" />`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To ensure both mouse and touch events are always handled, set the prop as `:listeners=\"'mouse and touch'\"`.","message":"The `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\"`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.1':90 '2':100,118 '2.5.0':101 '3':104 '3.0.0':105 'absolut':49 'allow':29 'although':106 'appear':176 'applic':167 'automat':60 'base':51 'behavior':154 'cadenc':170 'case':159 'cater':155 'compon':4,13 'comprehens':140 'configur':44 'contain':40,85 'content':36 'control':82,148 'current':182 'custom':80 'defin':39 'demonstr':116 'design':14 'develop':129 'differenti':135 'disabl':78 'doubl':68 'double-tap':67 'drag':21 'durat':46 'enhanc':128 'exampl':111 'experi':130 'explicit':173 'featur':42 'fine':146 'fine-grain':145 'function':22 'gestur':27 'global':119 'grain':147 'handl':84 'imag':24,35,54,162,189 'includ':75 'indic':95 'instal':108 'interact':73,166 'javascript':184 'librari':92,123 'like':43 'limit':48 'minimum':56 'mous':71 'offer':41,138 'option':76 'origin':53 'overflow':86 'pan':34,79,153 'peerdepend':94 'pinch':2,7,18,186 'pinch-zoom':17 'primarili':115 'project':133 'properti':143 'provid':16 'readm':114 'registr':120 'releas':169 'scale':32,57 'set':58,141 'ship':124 'simpl':161 'size':55 'special':11 'stabl':179 'state':174 'support':65,96 'syntax':121 'tap':69 'touch':26,188 'transit':45 'type':127 'typescript':126,132,191 'usag':110 'use':25,158 'user':30 'various':157 'version':89,183 'viewer':163 'vue':1,6,99,103,117,185 'vue-pinch-zoom':5 'vue.js':12 'wheel':72 'within':37 'zoom':3,8,19,47,62,81,151,187,190 'zoom-out':61","created_at":"2026-04-20T01:58:57.603905+00:00","updated_at":"2026-04-20T01:58:57.603905+00:00","problems":[{"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 }`.","cause":"The `pinch-zoom` component was not properly registered either globally or locally within your Vue application before being used in a template.","error":"[Vue warn]: Unknown custom element: <pinch-zoom> - did you register the component correctly?"},{"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.","cause":"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\"`.","error":"Property 'limitZoom' does not exist on type 'PinchZoomProps'."},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'component')"},{"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.","cause":"The `limitZoom` property received a string value that is neither a number nor the precise literal `\"original image size\"`, violating its prop type validation.","error":"[Vue warn]: Invalid prop: type check failed for prop \"limitZoom\". Expected Number, String with value \"original image size\", got String with value \"invalid-string\"."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"http://ivylab.space/pinch-zoom/vue","github":"https://github.com/drozhzhin-n-e/vue-pinch-zoom","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vue-pinch-zoom","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}