A simple, customizable, mobile-friendly image cropper for Vue.

Documentation · Live examples · Issues

v2 supports Vue 3. Vue 2 applications can stay on vue-croppa@1 (latest 1.x release: 1.3.8). See the Vue 3 guide, API, and migration guide.

npm install vue-croppa@2

<script setup lang="ts">
import { ref } from 'vue'
import { Croppa } from 'vue-croppa'
import 'vue-croppa/style.css'

const cropper = ref<InstanceType<typeof Croppa> | null>(null)

async function save() {
  const blob = await cropper.value?.promisedBlob('image/png')
  // Upload or download the Blob.
}
</script>

<template>
  <Croppa ref="cropper" :width="320" :height="240" />
  <button @click="save">Save crop</button>
</template>

The live Vue 3 preview uses the real v2 component.

Install v1 explicitly:

npm install vue-croppa@1

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

Vue.use(Croppa)

For script tags, pin v1 in CDN URLs: https://unpkg.com/vue-croppa@1/dist/vue-croppa.min.js and https://unpkg.com/vue-croppa@1/dist/vue-croppa.min.css. Unversioned unpkg.com/vue-croppa/dist/... URLs now resolve to v2 and return 404.

<croppa
  v-model="croppa"
  :width="400"
  :height="300"
  prevent-white-space
></croppa>

export default {
  data() {
    return {
      croppa: null,
    }
  },

  methods: {
    async getCroppedImage() {
      return this.croppa.promisedBlob('image/jpeg', 0.9)
    },
  },
}

For the smallest possible setup:

<croppa v-model="croppa"></croppa>

The v1 model resolves to the Croppa component instance, which exposes movement, zoom, rotation, metadata, and output methods.

• Drag to reposition the image
• Wheel and pinch zoom
• Rotation and horizontal / vertical flip
• File chooser and drag & drop
• File type and file size validation
• Local-file EXIF orientation handling
• Initial images
• Blob and data URL output
• Canvas access and draw hooks
• Save / restore transform metadata
• Passive synchronized previews
• Responsive auto-sizing
• Rounded and custom clipped output

The documentation examples are part of this repository—there are no CodePen embeds in the new docs.

The demo suite includes:

• Basic crop
• File input and drag/drop
• Move, zoom, rotate, and flip
• Zoom slider
• Responsive auto-sizing
• Blob / data URL output
• Upload and download recipes
• Metadata persistence
• Passive preview
• Watermark / draw hook
• Rounded and custom clipping
• Custom loading
• Image placeholder
• EXIF orientation hint

Those pages execute the actual repository bundle and are exercised in Chromium by Playwright. The original docs/simple-test.html harness is also adapted to deterministic local assets and kept as an additional compatibility check.

The full v1 reference is organized by task rather than duplicated into this README:

• Getting started
• Input & loading
• Manipulation & state
• Output & upload
• Customization
• Troubleshooting
• Complete API reference

In v1, the visible cropper dimensions and output resolution are coupled:

output width  = width × quality
output height = height × quality

In v2, the visible canvas and export use the same pixels at quality scale. Use autoSizing to follow a responsive container.

npm install
npm run dev

The historical v1 docs/build files remain under docs/ because they contain the current built bundle and broad simple-test.html compatibility harness.

cd site
npm install
npm run dev

Run the first-party browser verification:

cd site
npm run test:e2e

The docs build copies the local Vue 2 + vue-croppa bundle, adapts docs/simple-test.html to local deterministic assets, builds VitePress, and runs the demo suite in Chromium.

The Vue 3 / TypeScript package source is under v2/. Run npm run check there for typecheck, unit tests, and a library build.

ISC