vue-croppa

Vue Croppa

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

Documentation · Live examples · Issues

Version status

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.

Install for Vue 3

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.

Vue 2 / v1 archive

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.

Basic v1 usage

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

What v1 supports

• 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

Live v1 demos

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.

v1 documentation

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

A note about v1 sizing

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.

Development

v1 component

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.

Modern docs

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.

v2

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

License

ISC