Vue Cropper.js Wrapper Component

5.0.0 · active · verified Sun Apr 19

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.

Common errors

```
Failed to resolve component: vue-cropper
```
cause The VueCropper component was not properly registered or imported.

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.
```
TypeError: this.$refs.cropper.rotate is not a function
```
cause The component instance in the ref might not be available yet, or the method name is incorrect/deprecated for the installed version.

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`).

Warnings

breaking 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.
Fix: For Vue 3 projects, ensure `npm install vue-cropperjs@latest`. For Vue 2 projects, `npm install vue-cropperjs@4.2.0`.
breaking 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.
Fix: Update calls from `this.$refs.cropper.zoom()` to `this.$refs.cropper.relativeZoom()` and `this.$refs.cropper.crop()` to `this.$refs.cropper.initCrop()`.
gotcha 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.
Fix: Add `import 'cropperjs/dist/cropper.css';` to your main entry file or the component where `VueCropper` is used.

Install

npm install vue-cropperjs npm
yarn add vue-cropperjs yarn
pnpm add vue-cropperjs pnpm

Imports

VueCropper
wrong:
```
import { VueCropper } from 'vue-cropperjs';
```
correct:
```
import VueCropper from 'vue-cropperjs';
```
The component is exported as a default export for direct import.
Cropper.js CSS
```
import 'cropperjs/dist/cropper.css';
```
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.
Component Registration (Local)
wrong:
```
Vue.component('VueCropper', VueCropper); // For Vue 3, global registration is done differently or avoided.
```
correct:
```
import VueCropper from 'vue-cropperjs';
export default {
  components: { VueCropper }
}
```
Local component registration is the recommended approach in Vue 3. Global registration is possible via `app.component('vue-cropper', VueCropper)` in `main.js`.

Quickstart

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.

import { createApp, ref, onMounted } from 'vue';
import VueCropper from 'vue-cropperjs';
import 'cropperjs/dist/cropper.css';

const App = {
  components: { VueCropper },
  setup() {
    const cropperRef = ref(null);
    const imgSrc = ref('https://picsum.photos/800/600');
    const croppedImage = ref(null);

    const cropImage = () => {
      if (cropperRef.value) {
        croppedImage.value = cropperRef.value.getCroppedCanvas().toDataURL();
      }
    };

    const rotate = () => {
      if (cropperRef.value) {
        cropperRef.value.rotate(90);
      }
    };

    return {
      cropperRef,
      imgSrc,
      croppedImage,
      cropImage,
      rotate
    };
  },
  template: `
    <div>
      <h1>Image Cropper</h1>
      <div style="width: 600px; height: 400px; margin-bottom: 20px;">
        <vue-cropper
          ref="cropperRef"
          :src="imgSrc"
          alt="Source Image"
          :aspectRatio="16/9"
          :viewMode="1"
          @crop="cropImage"
        />
      </div>
      <button @click="cropImage">Get Cropped Image</button>
      <button @click="rotate">Rotate 90°</button>
      <div v-if="croppedImage" style="margin-top: 20px;">
        <h2>Cropped Image:</h2>
        <img :src="croppedImage" alt="Cropped Image" style="max-width: 100%; border: 1px solid #eee;"/>
      </div>
    </div>
  `
};

createApp(App).mount('#app');

view raw JSON →