Vue Image Crop Upload Component

3.0.3 · active · verified Wed Apr 22

vue-image-crop-upload is a Vue component designed for client-side image cropping and uploading, currently stable at version 3.0.3. It provides a rich UI for users to select, crop, and then upload images to a specified server endpoint. The component prioritizes a desktop user experience and explicitly advises against mobile use due to its design. Key differentiators include its compatibility with Vue 3 (since v3.0.0), support for older browsers like IE10+, and extensive customization options for the cropping interface, such as disabling circular or square previews and image rotation. While a specific release cadence isn't published, major version bumps appear tied to Vue framework updates, indicating stability rather than rapid iteration. It integrates easily into Vue applications, handling image selection, client-side manipulation, and direct HTTP upload with configurable parameters and headers.

Common errors

Warnings

Install

Imports

Quickstart

Demonstrates how to integrate `vue-image-crop-upload` into a Vue 3 application. It shows component registration, basic usage with `v-model` for visibility, setting custom `width`, `height`, upload `url`, `field` name, `params`, and `headers`. Event listeners for `crop-success`, `crop-upload-success`, and `crop-upload-fail` are included to handle the image cropping and upload lifecycle, with `process.env` placeholders for API keys.

import { createApp, ref } from 'vue';
import VueImageCropUpload from 'vue-image-crop-upload';

const app = createApp({
  components: {
    'vue-image-crop-upload': VueImageCropUpload
  },
  setup() {
    const show = ref(false);
    const params = ref({
      token: process.env.VUE_APP_UPLOAD_TOKEN ?? 'dummy_token',
      name: 'avatar'
    });
    const headers = ref({
      authorization: `Bearer ${process.env.VUE_APP_AUTH_KEY ?? ''}`
    });
    const imgDataUrl = ref('');

    const toggleShow = () => {
      show.value = !show.value;
    };

    const cropSuccess = (imgDataUrlLocal: string, field: string) => {
      console.log('Cropping successful. Field:', field);
      imgDataUrl.value = imgDataUrlLocal; // Update the preview
    };

    const cropUploadSuccess = (jsonData: any, field: string) => {
      console.log('Upload successful. JSON Data:', jsonData, 'Field:', field);
      alert('Upload success!');
      show.value = false; // Close modal on success
    };

    const cropUploadFail = (status: number, field: string) => {
      console.log('Upload failed. Status:', status, 'Field:', field);
      alert(`Upload failed with status: ${status}`);
    };

    return {
      show,
      params,
      headers,
      imgDataUrl,
      toggleShow,
      cropSuccess,
      cropUploadSuccess,
      cropUploadFail
    };
  },
  template: `
    <div id="app-container">
      <h1>Vue Image Crop Upload Demo</h1>
      <img v-if="imgDataUrl" :src="imgDataUrl" alt="Cropped Image Preview" style="max-width: 200px; max-height: 200px; border: 1px solid #ccc; margin-bottom: 20px;" />
      <button @click="toggleShow">Upload New Avatar</button>

      <vue-image-crop-upload
        v-model:show="show"
        :width="300"
        :height="300"
        url="/api/upload-avatar" <!-- Replace with your actual backend upload endpoint -->
        field="upload"
        img-format="png"
        :params="params"
        :headers="headers"
        @crop-success="cropSuccess"
        @crop-upload-success="cropUploadSuccess"
        @crop-upload-fail="cropUploadFail"
      ></vue-image-crop-upload>

      <p>This demo illustrates how to integrate and use the <code>vue-image-crop-upload</code> component in a Vue 3 application. It sets up basic visibility control, defines upload parameters and headers, and handles success and failure events. The <code>url</code> prop should point to a valid backend API endpoint capable of handling image uploads.</p>
    </div>
  `
});

app.mount('#app-container');

view raw JSON →