Vue Cropper

Common errors

• Cannot read properties of undefined (reading 'use')

  cause 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.
  fix For 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

  cause 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.
  fix Configure 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 | ...'

  cause 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.
  fix Ensure 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.

Warnings

• breaking The `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.
  Fix: Refer 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.
• gotcha When 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'.
  Fix: Ensure 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.
• gotcha Forgetting 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.
  Fix: Always include `import 'vue-cropper/dist/index.css';` in your main application entry file or directly within the component where `VueCropper` is used.
• gotcha Handling 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.
  Fix: Pre-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.
• deprecated Older 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.
  Fix: Adopt 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.

Install

• npm install vue-cropper npm
• yarn add vue-cropper yarn
• pnpm add vue-cropper pnpm

Imports

• VueCropper
  wrong:

  const VueCropper = require('vue-cropper');

  correct:

  import VueCropper from '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)
  wrong:

  import Cropper from 'vue-cropper';

  correct:

  import { VueCropper } 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)
  wrong:

  import type { InstanceType } from 'vue-cropper';

  correct:

  import type { InstanceType } from 'vue';

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

Quickstart

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>