{"id":17402,"library":"vue-image-crop-upload","title":"Vue Image Crop Upload Component","description":"vue-image-crop-upload is a Vue component designed for client-side image cropping and uploading, currently stable at version 3.0.3. It provides a rich UI for users to select, crop, and then upload images to a specified server endpoint. The component prioritizes a desktop user experience and explicitly advises against mobile use due to its design. Key differentiators include its compatibility with Vue 3 (since v3.0.0), support for older browsers like IE10+, and extensive customization options for the cropping interface, such as disabling circular or square previews and image rotation. While a specific release cadence isn't published, major version bumps appear tied to Vue framework updates, indicating stability rather than rapid iteration. It integrates easily into Vue applications, handling image selection, client-side manipulation, and direct HTTP upload with configurable parameters and headers.","status":"active","version":"3.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/dai-siki/vue-image-crop-upload","tags":["javascript","vue","image","picture","photo","uploader","crop","cropper","file"],"install":[{"cmd":"npm install vue-image-crop-upload","lang":"bash","label":"npm"},{"cmd":"yarn add vue-image-crop-upload","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-image-crop-upload","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, the component is built for Vue 3.","package":"vue","optional":false}],"imports":[{"note":"Since version 3.0.0, the package is ESM-first and designed for Vue 3, making CommonJS `require` less suitable for modern projects.","wrong":"const VueImageCropUpload = require('vue-image-crop-upload');","symbol":"VueImageCropUpload","correct":"import VueImageCropUpload from 'vue-image-crop-upload';"},{"note":"Standard local component registration within a Vue 3 component. The component is typically used directly in templates.","symbol":"Component Registration (Local)","correct":"import VueImageCropUpload from 'vue-image-crop-upload';\nexport default {\n components: { VueImageCropUpload },\n // ...\n}"},{"note":"For Vue 3 applications, global components are registered on the application instance, not a global Vue object like in Vue 2.","wrong":"Vue.component('vue-image-crop-upload', VueImageCropUpload);","symbol":"Component Registration (Global)","correct":"import VueImageCropUpload from 'vue-image-crop-upload';\ncreateApp(App).component('vue-image-crop-upload', VueImageCropUpload).mount('#app');"}],"quickstart":{"code":"import { createApp, ref } from 'vue';\nimport VueImageCropUpload from 'vue-image-crop-upload';\n\nconst app = createApp({\n components: {\n 'vue-image-crop-upload': VueImageCropUpload\n },\n setup() {\n const show = ref(false);\n const params = ref({\n token: process.env.VUE_APP_UPLOAD_TOKEN ?? 'dummy_token',\n name: 'avatar'\n });\n const headers = ref({\n authorization: `Bearer ${process.env.VUE_APP_AUTH_KEY ?? ''}`\n });\n const imgDataUrl = ref('');\n\n const toggleShow = () => {\n show.value = !show.value;\n };\n\n const cropSuccess = (imgDataUrlLocal: string, field: string) => {\n console.log('Cropping successful. Field:', field);\n imgDataUrl.value = imgDataUrlLocal; // Update the preview\n };\n\n const cropUploadSuccess = (jsonData: any, field: string) => {\n console.log('Upload successful. JSON Data:', jsonData, 'Field:', field);\n alert('Upload success!');\n show.value = false; // Close modal on success\n };\n\n const cropUploadFail = (status: number, field: string) => {\n console.log('Upload failed. Status:', status, 'Field:', field);\n alert(`Upload failed with status: ${status}`);\n };\n\n return {\n show,\n params,\n headers,\n imgDataUrl,\n toggleShow,\n cropSuccess,\n cropUploadSuccess,\n cropUploadFail\n };\n },\n template: `\n
\n

Vue Image Crop Upload Demo

\n \"Cropped\n \n\n \n field=\"upload\"\n img-format=\"png\"\n :params=\"params\"\n :headers=\"headers\"\n @crop-success=\"cropSuccess\"\n @crop-upload-success=\"cropUploadSuccess\"\n @crop-upload-fail=\"cropUploadFail\"\n >\n\n

This demo illustrates how to integrate and use the vue-image-crop-upload component in a Vue 3 application. It sets up basic visibility control, defines upload parameters and headers, and handles success and failure events. The url prop should point to a valid backend API endpoint capable of handling image uploads.

\n
\n `\n});\n\napp.mount('#app-container');","lang":"typescript","description":"Demonstrates how to integrate `vue-image-crop-upload` into a Vue 3 application. It shows component registration, basic usage with `v-model` for visibility, setting custom `width`, `height`, upload `url`, `field` name, `params`, and `headers`. Event listeners for `crop-success`, `crop-upload-success`, and `crop-upload-fail` are included to handle the image cropping and upload lifecycle, with `process.env` placeholders for API keys."},"warnings":[{"fix":"For Vue 2 projects, downgrade to a version compatible with Vue 2 (e.g., `npm install vue-image-crop-upload@^2`). For Vue 3 projects, ensure you are on v3.0.0 or higher.","message":"Version 3.0.0 introduced full compatibility with Vue 3. This means projects built on Vue 2 will be incompatible and should use an older version (e.g., ^2.x.x) of the component.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consider using alternative image cropping libraries optimized for mobile responsiveness or implement conditional rendering to hide/disable this component on mobile viewports.","message":"The component is explicitly 'not recommended for use on the mobile side'. Developers should be aware of this limitation and implement alternative solutions or responsive adjustments for mobile users.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure the `url` prop is set to a valid backend endpoint for image processing and upload. Double-check its value and that the endpoint is reachable.","message":"If the `url` prop is not provided or is an empty string, the component will not perform an upload, leading to silent failure of the upload functionality.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you have `import VueImageCropUpload from 'vue-image-crop-upload';` at the top of your component/main file and that it's listed in the `components` option (for local use) or globally registered with `app.component()` (for global use).","cause":"The component was not properly imported or registered in your Vue application.","error":"Failed to resolve component: vue-image-crop-upload"},{"fix":"Verify that `imgFormat` is 'jpg' or 'png' and `imgBgc` is a valid color string (e.g., '#fff') if `imgFormat` is 'jpg'. Check all props for correct types as specified in the documentation.","cause":"This often occurs when the component's internal methods expect certain props or data to be defined, but they are missing or incorrectly typed, possibly due to an invalid `imgFormat` or `imgBgc` value.","error":"TypeError: Cannot read properties of undefined (reading 'length') in vue-image-crop-upload.umd.js"},{"fix":"Double-check the `url` prop's value to ensure it's a correct and accessible API endpoint. Verify your backend server is running and configured to handle the POST request at that specific path.","cause":"The `url` prop provided to the component points to an invalid or unreachable backend endpoint, or the path is incorrect.","error":"ERR_NAME_NOT_RESOLVED or 404 Not Found in console network tab for upload request"}],"ecosystem":"npm","meta_description":null}