{"id":12447,"library":"vue-cropperjs","title":"Vue Cropper.js Wrapper Component","description":"Vue-cropperjs is a Vue.js wrapper component for the popular Cropper.js library, enabling image cropping, rotating, and zooming functionalities within Vue 3 applications. The current stable version is 5.0.0, which targets Vue 3.x.x. Previous versions (e.g., 4.2.0) supported Vue 2.x.x, indicating a clear version split for different Vue major versions. The project appears to have an active maintenance cadence, aligning with major Vue releases and dependency updates. Key differentiators include its direct integration with Vue's reactivity system and component model, simplifying the use of Cropper.js without direct DOM manipulation. It primarily acts as a direct passthrough for most Cropper.js options and methods, offering a thin, idiomatic Vue layer over the core JavaScript library.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/Agontuk/vue-cropperjs","tags":["javascript","vue","vuejs","cropper","cropperjs","component"],"install":[{"cmd":"npm install vue-cropperjs","lang":"bash","label":"npm"},{"cmd":"yarn add vue-cropperjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-cropperjs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue 3.x.x functionality.","package":"vue","optional":false},{"reason":"Core image cropping library; vue-cropperjs is a wrapper around it.","package":"cropperjs","optional":false}],"imports":[{"note":"The component is exported as a default export for direct import.","wrong":"import { VueCropper } from 'vue-cropperjs';","symbol":"VueCropper","correct":"import VueCropper from 'vue-cropperjs';"},{"note":"The CSS for cropperjs is a separate import and is crucial for correct styling and functionality. This should be imported once globally or within the component where VueCropper is used.","symbol":"Cropper.js CSS","correct":"import 'cropperjs/dist/cropper.css';"},{"note":"Local component registration is the recommended approach in Vue 3. Global registration is possible via `app.component('vue-cropper', VueCropper)` in `main.js`.","wrong":"Vue.component('VueCropper', VueCropper); // For Vue 3, global registration is done differently or avoided.","symbol":"Component Registration (Local)","correct":"import VueCropper from 'vue-cropperjs';\nexport default {\n components: { VueCropper }\n}"}],"quickstart":{"code":"import { createApp, ref, onMounted } from 'vue';\nimport VueCropper from 'vue-cropperjs';\nimport 'cropperjs/dist/cropper.css';\n\nconst App = {\n components: { VueCropper },\n setup() {\n const cropperRef = ref(null);\n const imgSrc = ref('https://picsum.photos/800/600');\n const croppedImage = ref(null);\n\n const cropImage = () => {\n if (cropperRef.value) {\n croppedImage.value = cropperRef.value.getCroppedCanvas().toDataURL();\n }\n };\n\n const rotate = () => {\n if (cropperRef.value) {\n cropperRef.value.rotate(90);\n }\n };\n\n return {\n cropperRef,\n imgSrc,\n croppedImage,\n cropImage,\n rotate\n };\n },\n template: `\n
\n

Image Cropper

\n
\n \n
\n \n \n
\n

Cropped Image:

\n \"Cropped\n
\n
\n `\n};\n\ncreateApp(App).mount('#app');","lang":"typescript","description":"This quickstart demonstrates how to integrate `vue-cropperjs` into a Vue 3 application, including importing the component and its CSS, displaying an image for cropping, and using a ref to access the underlying Cropper.js instance to perform actions like getting the cropped image and rotating it."},"warnings":[{"fix":"For Vue 3 projects, ensure `npm install vue-cropperjs@latest`. For Vue 2 projects, `npm install vue-cropperjs@4.2.0`.","message":"Version 5.0.0 and above are exclusively compatible with Vue 3. Applications using Vue 2.x.x must use vue-cropperjs version 4.2.0 or earlier.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update calls from `this.$refs.cropper.zoom()` to `this.$refs.cropper.relativeZoom()` and `this.$refs.cropper.crop()` to `this.$refs.cropper.initCrop()`.","message":"The `zoom` method has been renamed to `relativeZoom` and the `crop` method has been renamed to `initCrop` to avoid conflicts or improve clarity in recent versions.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Add `import 'cropperjs/dist/cropper.css';` to your main entry file or the component where `VueCropper` is used.","message":"The `cropperjs/dist/cropper.css` file must be explicitly imported for the component to render correctly. Without it, the cropper UI will be malformed or invisible.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `import VueCropper from 'vue-cropperjs';` and `components: { VueCropper }` in your component, or globally register it with `app.component('vue-cropper', VueCropper)` in Vue 3.","cause":"The VueCropper component was not properly registered or imported.","error":"Failed to resolve component: vue-cropper"},{"fix":"Check that the component is mounted and `cropperRef.value` (or `this.$refs.cropper`) exists before calling methods. Also, verify method names against documentation, especially for renamed methods like `relativeZoom` (formerly `zoom`) and `initCrop` (formerly `crop`).","cause":"The component instance in the ref might not be available yet, or the method name is incorrect/deprecated for the installed version.","error":"TypeError: this.$refs.cropper.rotate is not a function"}],"ecosystem":"npm"}