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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VueImageCropUpload
✓ import VueImageCropUpload from 'vue-image-crop-upload';
✗ const VueImageCropUpload = require('vue-image-crop-upload');
Since version 3.0.0, the package is ESM-first and designed for Vue 3, making CommonJS `require` less suitable for modern projects.
Component Registration (Local)
✓ import VueImageCropUpload from 'vue-image-crop-upload';
export default {
components: { VueImageCropUpload },
// ...
}
Standard local component registration within a Vue 3 component. The component is typically used directly in templates.
Component Registration (Global)
✓ import VueImageCropUpload from 'vue-image-crop-upload';
createApp(App).component('vue-image-crop-upload', VueImageCropUpload).mount('#app');
✗ Vue.component('vue-image-crop-upload', VueImageCropUpload);
For Vue 3 applications, global components are registered on the application instance, not a global Vue object like in Vue 2.
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.
import { createApp, ref } from 'vue';
import VueImageCropUpload from 'vue-image-crop-upload';
const app = createApp({
components: {
'vue-image-crop-upload': VueImageCropUpload
},
setup() {
const show = ref(false);
const params = ref({
token: process.env.VUE_APP_UPLOAD_TOKEN ?? 'dummy_token',
name: 'avatar'
});
const headers = ref({
authorization: `Bearer ${process.env.VUE_APP_AUTH_KEY ?? ''}`
});
const imgDataUrl = ref('');
const toggleShow = () => {
show.value = !show.value;
};
const cropSuccess = (imgDataUrlLocal: string, field: string) => {
console.log('Cropping successful. Field:', field);
imgDataUrl.value = imgDataUrlLocal; // Update the preview
};
const cropUploadSuccess = (jsonData: any, field: string) => {
console.log('Upload successful. JSON Data:', jsonData, 'Field:', field);
alert('Upload success!');
show.value = false; // Close modal on success
};
const cropUploadFail = (status: number, field: string) => {
console.log('Upload failed. Status:', status, 'Field:', field);
alert(`Upload failed with status: ${status}`);
};
return {
show,
params,
headers,
imgDataUrl,
toggleShow,
cropSuccess,
cropUploadSuccess,
cropUploadFail
};
},
template: `
<div id="app-container">
<h1>Vue Image Crop Upload Demo</h1>
<img v-if="imgDataUrl" :src="imgDataUrl" alt="Cropped Image Preview" style="max-width: 200px; max-height: 200px; border: 1px solid #ccc; margin-bottom: 20px;" />
<button @click="toggleShow">Upload New Avatar</button>
<vue-image-crop-upload
v-model:show="show"
:width="300"
:height="300"
url="/api/upload-avatar" <!-- Replace with your actual backend upload endpoint -->
field="upload"
img-format="png"
:params="params"
:headers="headers"
@crop-success="cropSuccess"
@crop-upload-success="cropUploadSuccess"
@crop-upload-fail="cropUploadFail"
></vue-image-crop-upload>
<p>This demo illustrates how to integrate and use the <code>vue-image-crop-upload</code> component in a Vue 3 application. It sets up basic visibility control, defines upload parameters and headers, and handles success and failure events. The <code>url</code> prop should point to a valid backend API endpoint capable of handling image uploads.</p>
</div>
`
});
app.mount('#app-container');
Errors
Common errors & fixes
Failed to resolve component: vue-image-crop-upload
The component was not properly imported or registered in your Vue application.
fixEnsure 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).
TypeError: Cannot read properties of undefined (reading 'length') in vue-image-crop-upload.umd.js
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.
fixVerify 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.
ERR_NAME_NOT_RESOLVED or 404 Not Found in console network tab for upload request
The `url` prop provided to the component points to an invalid or unreachable backend endpoint, or the path is incorrect.
fixDouble-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.
Audit
Dependencies
vuerequiredPeer dependency, the component is built for Vue 3.