Vue Picture Cropper

Common errors

• Cannot find module 'cropperjs' or its corresponding type declarations.

  cause The `cropperjs` library, a peer dependency, has not been installed.
  fix Install `cropperjs`: `npm install cropperjs@^1` or `yarn add cropperjs@^1`.

• TypeError: (0, vue_picture_cropper__WEBPACK_IMPORTED_MODULE_0__.useCropper) is not a function

  cause Attempting to use the `useCropper` composable on a version of `vue-picture-cropper` prior to `v1.0.0`, or an incorrect named import.
  fix Upgrade `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)

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

Warnings

• breaking Version 1.0.0 introduced significant breaking changes, including enhanced type constraints, unified public exports, component-scoped cropper instances replacing module-level ones, and the introduction of the `useCropper` composable. Direct access to the Cropper.js instance and event handling might have changed.
  Fix: Refer to the official 'Migrating from v0.x' guide and online examples for step-by-step migration instructions. Update import paths and usage of component properties/methods.
• gotcha The `cropperjs` library is a peer dependency and must be installed separately alongside `vue-picture-cropper`. Forgetting to install it will lead to runtime errors.
  Fix: Ensure `cropperjs` is installed: `npm install vue-picture-cropper cropperjs@^1`.
• gotcha The `getBlob`, `getFile`, and `getBase64` methods are asynchronous operations since v0.3.0 (for `getBlob`) due to their reliance on canvas processing to generate higher quality output and correctly handle large images, which was a fix for previous white-border issues.
  Fix: Always `await` the calls to `cropper.getBlob()`, `cropper.getFile()`, and `cropper.getBase64()` to correctly handle the asynchronous nature and receive the result.
• gotcha Prior to v0.1.11, if cropping failed and `base64` was empty, converting it to a `blob` could lead to application crashes. This was fixed to return `null` instead.
  Fix: Upgrade to `v0.1.11` or later. If on an older version, add explicit checks for `null` or empty results before further processing cropped data.

Install

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

Imports

• PictureCropper
  wrong:

  import { PictureCropper } from 'vue-picture-cropper'

  correct:

  import PictureCropper from 'vue-picture-cropper'

  The main component is exported as a default export, as shown in official examples.
• useCropper
  wrong:

  import useCropper from 'vue-picture-cropper'

  correct:

  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
  wrong:

  import { CropperResult } from 'vue-picture-cropper'

  correct:

  import type { 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.

Quickstart

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>