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.
VueCropper
✓ import VueCropper from 'vue-cropper';
✗ const VueCropper = require('vue-cropper');
Standard ESM default import for the Vue component. Used for global registration (`Vue.use(VueCropper)` or `app.use(VueCropper)`) and local component registration.
VueCropper (named)
✓ import { VueCropper } from 'vue-cropper';
✗ import Cropper from 'vue-cropper';
ESM named import for the component. This syntax also works due to dual exports (`default` and named `VueCropper`) provided by the library, offering an alternative to the default import style.
InstanceType (for refs)
✓ import type { InstanceType } from 'vue';
✗ import type { InstanceType } from 'vue-cropper';
While `vue-cropper` itself does not export specific types for its instance, developers commonly use `InstanceType<typeof VueCropper>` from Vue's core for robust TypeScript typing of component refs, allowing access to methods like `getCropData`.
Demonstrates basic image loading, displaying the cropper, allowing the user to select a crop area, and extracting the cropped image as a Base64 string for preview or upload, using Vue 3 Composition API with TypeScript. It also includes the necessary CSS import.
<template>
<div class="cropper-container">
<input type="file" accept="image/*" @change="handleFileChange" />
<div class="cropper-wrapper" v-if="imgSrc">
<VueCropper
ref="cropperRef"
:img="imgSrc"
:output-size="outputSize"
:output-type="outputType"
:info="true"
:full="true"
:fixed-box="false"
:can-move="true"
:can-move-box="true"
:original="false"
:auto-crop="true"
:auto-crop-width="200"
:auto-crop-height="150"
@realTime="realTimePreview"
></VueCropper>
</div>
<button @click="cropImage" v-if="imgSrc">Crop Image</button>
<div class="preview" v-if="previewImg">
<h3>Preview:</h3>
<img :src="previewImg" alt="Cropped Image Preview" />
</div>
</div>
</template>
<script setup lang="ts">
import { ref, watch } from 'vue';
import VueCropper from 'vue-cropper';
import 'vue-cropper/dist/index.css'; // Don't forget to import the CSS
// Define the type for the VueCropper instance
interface VueCropperInstance {
getCropData: (callback: (data: string) => void) => void;
getCropBlob: (callback: (blob: Blob) => void) => void;
// Add other methods if you plan to use them, e.g., setCropBoxData, zoom
}
const cropperRef = ref<VueCropperInstance | null>(null);
const imgSrc = ref<string | null>(null);
const previewImg = ref<string | null>(null);
const outputSize = ref(1); // Output image quality (0 to 1)
const outputType = ref('jpeg'); // Output image format (jpeg, png, webp)
const handleFileChange = (e: Event) => {
const file = (e.target as HTMLInputElement).files?.[0];
if (file) {
const reader = new FileReader();
reader.onload = (event) => {
imgSrc.value = event.target?.result as string;
};
reader.readAsDataURL(file);
}
};
const cropImage = () => {
if (cropperRef.value) {
cropperRef.value.getCropData((data: string) => {
previewImg.value = data;
console.log('Cropped Base64:', data.substring(0, 50) + '...');
// For uploading blob:
// cropperRef.value?.getCropBlob((blob: Blob) => {
// console.log('Cropped Blob:', blob);
// // You can upload the blob to your server here
// });
});
}
};
const realTimePreview = (data: { img: string }) => {
// Optional: Update a smaller preview in real-time as the user crops
// For this quickstart, we'll just show the final crop on button click.
// If you want a live preview, you can set previewImg.value = data.img here.
};
// Watch for changes in imgSrc to reset preview when a new image is selected
watch(imgSrc, () => {
previewImg.value = null;
});
</script>
<style scoped>
.cropper-container {
display: flex;
flex-direction: column;
align-items: center;
gap: 20px;
padding: 20px;
border: 1px solid #eee;
border-radius: 8px;
max-width: 600px;
margin: 20px auto;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.05);
}
.cropper-wrapper {
width: 100%;
max-width: 500px;
height: 300px;
background-color: #f8f8f8;
border: 1px dashed #ccc;
display: flex;
justify-content: center;
align-items: center;
}
.preview {
margin-top: 20px;
text-align: center;
}
.preview img {
max-width: 100%;
height: auto;
border: 1px solid #ddd;
border-radius: 4px;
}
input[type="file"] {
padding: 10px;
border: 1px solid #ccc;
border-radius: 4px;
cursor: pointer;
}
button {
background-color: #42b983;
color: white;
border: none;
padding: 10px 20px;
border-radius: 4px;
cursor: pointer;
font-size: 16px;
transition: background-color 0.2s ease;
}
button:hover {
background-color: #368a6f;
}
</style>
Debug
Known issues
breakingThe `vue-cropper` package underwent significant changes between `0.x` and `1.x` to introduce native support for Vue 3. While `0.x` was primarily for Vue 2, `1.x` is compatible with both Vue 2 and Vue 3. Migration from `0.x` to `1.x` may involve adjusting component registration methods and prop names, although the core API remains similar.fixRefer to the official GitHub repository's `README` for `1.x` usage examples. For Vue 3, prefer `app.use(VueCropper)` for global registration or local component import. Ensure you are using the correct build for your Vue version if manual configuration is needed.
affects: <1.0.0
gotchaWhen attempting to crop images loaded from a different origin (domain, port, or protocol), browsers enforce Cross-Origin Resource Sharing (CORS) policies. This can prevent the `vue-cropper` component from accessing image data on the canvas, leading to errors like 'Tainted canvases cannot be exported' or 'Image load failed'.fixEnsure the image server sends appropriate `Access-Control-Allow-Origin` headers (e.g., `Access-Control-Allow-Origin: *` or specific origin). Alternatively, proxy the images through your own backend or consider server-side cropping.
affects: >=0.6.5
gotchaForgetting to import the component's CSS styles (`import 'vue-cropper/dist/index.css';`) is a common mistake, leading to a non-functional or unstyled cropper component.fixAlways include `import 'vue-cropper/dist/index.css';` in your main application entry file or directly within the component where `VueCropper` is used.
affects: >=0.6.5
gotchaHandling large images, especially on less powerful devices or older browsers, can lead to performance issues, browser crashes, or slow responsiveness during cropping operations. The underlying `cropperjs` library may struggle with extremely high-resolution images.fixPre-process large images on the server-side to a reasonable resolution before sending them to the client. Implement client-side image resizing before passing them to the cropper if server-side processing is not an option. Optimize `output-size` and `output-type` props for performance.
affects: >=0.6.5
deprecatedOlder global API methods like `$on`, `$off`, `$once`, `$children`, and `filters` were removed in Vue 3. Applications migrating from Vue 2 to Vue 3 that heavily relied on these global methods for event communication or direct child component access will need refactoring.fixAdopt Vue 3's Composition API for component communication (e.g., `emit`, `provide`/`inject`, event bus libraries) and leverage component references (refs) for direct interaction where appropriate. Use standard JavaScript string manipulation instead of Vue filters.
affects: <3.0.0 (Vue core), `vue-cropper` versions primarily for Vue 2
Errors
Common errors & fixes
Cannot read properties of undefined (reading 'use')
Attempting to globally register the VueCropper plugin in a Vue 3 application using the Vue 2 `Vue.use()` syntax, or `Vue` is not correctly imported/defined.
fixFor Vue 3, use `app.use(VueCropper)` where `app` is your Vue application instance (e.g., `const app = createApp(App); app.use(VueCropper); app.mount('#app');`). For Vue 2, ensure `import Vue from 'vue';` and then `Vue.use(VueCropper);`. Tainted canvases cannot be exported
This error occurs when `vue-cropper` tries to extract image data (e.g., `getCropData`, `getCropBlob`) from a canvas that contains content loaded from a different origin without proper CORS headers.
fixConfigure the server hosting the image to send `Access-Control-Allow-Origin` headers. For development, you might use a browser extension to disable CORS, but this is not a production solution. Alternatively, load images via a proxy on the same origin as your application.
Property 'getCropData' does not exist on type 'Vue | Element | ...'
This TypeScript error typically arises when using `ref` to reference the `VueCropper` component in a Vue 3 `<script setup>` block, but the ref's type is not correctly specified, or the component instance isn't available yet.
fixEnsure the ref is correctly typed as the `VueCropper` component instance. For example, `const cropperRef = ref<InstanceType<typeof VueCropper> | null>(null);` or define an interface for the component's methods as shown in the quickstart. Also, ensure the component is mounted before trying to access its methods.
Audit
Dependencies
vuerequiredPeer dependency for runtime Vue integration.