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.
PictureCropper
✓ import PictureCropper from 'vue-picture-cropper'
✗ import { PictureCropper } from 'vue-picture-cropper'
The main component is exported as a default export, as shown in official examples.
useCropper
✓ import { useCropper } from 'vue-picture-cropper'
✗ import useCropper from 'vue-picture-cropper'
The `useCropper` composable was introduced in v1.0.0 and is a named export. Ensure you are on v1.0.0 or later.
CropperResult
✓ import type { CropperResult } from 'vue-picture-cropper'
✗ import { CropperResult } from 'vue-picture-cropper'
Import types using `import type` for better tree-shaking and clarity in TypeScript projects. Type definitions were refined in v0.6.0 and enhanced in v1.0.0.
This quickstart demonstrates how to install `vue-picture-cropper` and `cropperjs`, select an image, display the cropper component, and then use the `useCropper` composable to retrieve the cropped image as a Blob for preview.
<!-- App.vue -->
<template>
<div class="container">
<h1>Image Cropper</h1>
<input type="file" accept="image/*" @change="selectFile" />
<div v-if="imageSrc">
<PictureCropper
:boxStyle="{ width: '100%', height: '300px', backgroundColor: '#f8f8f8', margin: 'auto' }"
:img="imageSrc"
:options="{
viewMode: 1,
dragMode: 'move',
aspectRatio: 1 / 1,
cropBoxResizable: true
}"
@ready="cropperReady"
/>
<button @click="cropImage">Crop Image</button>
<div v-if="croppedImageBlob">
<h2>Cropped Image Preview</h2>
<img :src="croppedImageBlob" alt="Cropped" style="max-width: 100%;" />
</div>
</div>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import PictureCropper, { useCropper } from 'vue-picture-cropper';
const imageSrc = ref<string | null>(null);
const croppedImageBlob = ref<string | null>(null);
const { getCropperRef, getCropper, setCropper } = useCropper();
const selectFile = (e: Event) => {
const target = e.target as HTMLInputElement;
if (target.files && target.files.length) {
const file = target.files[0];
imageSrc.value = URL.createObjectURL(file);
}
};
const cropperReady = () => {
console.log('Cropper is ready!');
// You can set options or perform actions when cropper is ready
// For example, setCropper(getCropperRef().value.cropperInstance); // If you need direct Cropper.js instance
};
const cropImage = async () => {
const cropper = getCropper(); // Get the current cropper instance via composable
if (cropper) {
const blob = await cropper.getBlob();
if (blob) {
croppedImageBlob.value = URL.createObjectURL(blob);
console.log('Cropped image blob:', blob);
} else {
console.error('Failed to get cropped image blob.');
}
}
};
</script>
<style>
.container {
max-width: 600px;
margin: 20px auto;
padding: 20px;
border: 1px solid #eee;
border-radius: 8px;
font-family: sans-serif;
}
button {
margin-top: 20px;
padding: 10px 15px;
background-color: #3fb984;
color: white;
border: none;
border-radius: 4px;
cursor: pointer;
}
</style>
Errors
Common errors & fixes
Cannot find module 'cropperjs' or its corresponding type declarations.
The `cropperjs` library, a peer dependency, has not been installed.
fixInstall `cropperjs`: `npm install cropperjs@^1` or `yarn add cropperjs@^1`.
TypeError: (0, vue_picture_cropper__WEBPACK_IMPORTED_MODULE_0__.useCropper) is not a function
Attempting to use the `useCropper` composable on a version of `vue-picture-cropper` prior to `v1.0.0`, or an incorrect named import.
fixUpgrade `vue-picture-cropper` to `v1.0.0` or higher (`npm install vue-picture-cropper@^1`) and ensure it's imported correctly as a named export: `import { useCropper } from 'vue-picture-cropper'`. Property 'getBlob' does not exist on type '(...)' (TypeScript error)
This error often occurs when `getBlob()` is called synchronously or on an undefined cropper instance, or when the TypeScript context doesn't correctly infer the `CropperResult` type.
fixEnsure you are awaiting `getBlob()` as it's an asynchronous operation. Also, make sure the `cropper` instance (e.g., obtained from `useCropper().getCropper()`) is valid before attempting to call methods on it.
Audit
Dependencies
cropperjsrequiredCore image cropping logic; peer dependency.
vuerequiredVue 3 framework dependency; peer dependency.