Vue Image Cropper Component

Common errors

• ReferenceError: window is not defined

  cause The package attempts to access the `window` object during server-side rendering (SSR), which is only available in a browser environment.
  fix Implement SSR-specific checks or dynamically import the component only on the client-side. For Nuxt.js, use `<client-only><croppa ...></client-only>` or register the component as a client-side plugin.

• TypeError: Cannot read properties of undefined (reading 'hasImage')

  cause This usually occurs when the `v-model` bound `croppa` object has not been properly initialized or the component hasn't rendered yet, meaning the API methods are not available.
  fix Ensure `myCroppa: {}` is defined in your component's `data` property, and any calls to `myCroppa` methods are made after the component is mounted or after an image has been loaded (e.g., in a method triggered by user interaction).

• Error: Component name "croppa" has already been registered.

  cause Attempting to call `Vue.use(Croppa)` or `Vue.component('croppa', Croppa.component)` multiple times or in different modules within the same Vue instance.
  fix Ensure `Vue.use(Croppa)` is called only once, typically in your main `main.js` or `app.js` file. If using multiple Vue apps, register it separately for each, or customize the component name to avoid clashes.

Warnings

• breaking The `v-model` behavior for the cropper component has undergone changes. Prior to v1.0.0, the `v-model` prop might have behaved differently or had different expectations regarding the component's internal state binding.
  Fix: Ensure `v-model` is correctly bound to an empty object, e.g., `data: { myCroppa: {} }`, to correctly access the component's API methods.
• gotcha The `replace-drop` prop, which controls whether dropping a new image replaces the current one without explicit removal, defaults to `false` for backward compatibility. This might lead to unexpected behavior for users expecting the new image to automatically replace the old one.
  Fix: To enable automatic replacement on drag and drop, explicitly set `:replace-drop="true"` on the `<croppa>` component.
• gotcha When using `Vue.use(Croppa)`, the component is globally registered under the name `<croppa>`. If this name conflicts with existing components or you prefer a custom name, you need to specify it during plugin installation.
  Fix: Use `Vue.use(Croppa, { componentName: 'my-custom-cropper' });` to register the component with a different name.
• gotcha The `width` and `height` props are ignored if `auto-sizing` is set to `true`. In this mode, the cropper will adjust to its container's size, which can be useful for responsive layouts but might override explicit dimensions.
  Fix: If you need fixed dimensions, ensure `auto-sizing` is `false` (its default). For responsive behavior, set `:auto-sizing="true"` and manage the container's dimensions via CSS.
• gotcha The component is primarily designed for Vue 2.0. While it might work in a compatibility layer for Vue 3, official support for Vue 3 or Composition API is not explicitly stated, potentially leading to integration issues.
  Fix: Consider using alternative image cropper libraries that are explicitly built for Vue 3 if you are working on a Vue 3 project.

Install

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

Imports

• Croppa
  wrong:

  import { Croppa } from 'vue-croppa';

  correct:

  import Croppa from 'vue-croppa';

  Croppa is a default export, used for installing the plugin and accessing the component object.
• Croppa styles

  import 'vue-croppa/dist/vue-croppa.css';

  The CSS must be imported separately for styling the cropper component.
• Vue.use(Croppa)

  Vue.use(Croppa);

  Registers the cropper component globally. By default, it registers as `<croppa>`. You can customize the component name via `Vue.use(Croppa, { componentName: 'my-cropper' })`.

Quickstart

This quickstart initializes a Vue application with the croppa component. It demonstrates how to integrate the component, bind it with `v-model`, and programmatically access its API to generate and upload a cropped image as a Blob.

import Vue from 'vue';
import Croppa from 'vue-croppa';
import 'vue-croppa/dist/vue-croppa.css';

Vue.use(Croppa);

new Vue({
  el: '#app',
  template: `
    <div>
      <croppa v-model="myCroppa" :width="400" :height="400" :placeholder="'Drag & Drop or Click to Choose'" :quality="2"></croppa>
      <button @click="uploadCroppedImage">Upload Cropped Image</button>
    </div>
  `,
  data: {
    myCroppa: {}
  },
  methods: {
    uploadCroppedImage() {
      if (!this.myCroppa.hasImage()) {
        alert('Please choose an image first!');
        return;
      }
      this.myCroppa.generateBlob(
        blob => {
          // In a real application, you'd upload this blob to a server.
          // For demonstration, we'll just log its size and type.
          console.log('Generated Blob:', blob);
          console.log(`Type: ${blob.type}, Size: ${blob.size} bytes`);
          // Example: const formData = new FormData();
          // formData.append('image', blob, 'cropped-image.jpeg');
          // fetch('/upload', { method: 'POST', body: formData });
          alert('Image blob generated and logged to console!');
        },
        'image/jpeg',
        0.8
      ); // 80% compressed jpeg file
    }
  }
});