vue-cropper: the Vue 2 image cropper whose own README points Vue 3 users elsewhere

What vue-cropper solves, and which Vue it solves it for

The plugin covers one job: letting a user position a rectangular crop box over an image inside a Vue component, then reading the cropped pixels back as data. The props table shows the shape of that job. img takes a URL, a base64 string or a blob. outputSize is a quality multiplier from 0.1 to 1. outputType picks jpeg, png or webp. The crop box itself is configured with autoCrop, autoCropWidth, autoCropHeight, fixed and fixedNumber, so a form that needs a square avatar can open with a 1:1 box already drawn.

The audience question is not cosmetic here. The README opens by telling Vue 3 users to use a different repository, cropper-next-vue, described as an independently released Vue 3 cropping library with rotated-boundary handling, image confinement to the crop box or container, high-DPI export and real-time preview. The package.json in this repository lists vue ^2.5.17 and vue-template-compiler ^2.5.17 among its devDependencies, and the Vue 2 import path is a plain named import. Treat this repository as a Vue 2 tool that still carries a Vue 3 entry point, not as a library with equal support on both.

How the crop box, the image and the export path fit together

Everything is driven through the component instance. You pass the source image in through the img prop, and the component renders it inside whatever element you wrap around it. The README states plainly that the component needs an outer container with a width and a height set; the crop box defaults to 80 percent of that container when autoCropWidth and autoCropHeight are left alone.

Interaction state is exposed rather than hidden. The @realTime event fires with a payload the README uses to build preview thumbnails: it spreads previews.div and previews.img onto nested div and img elements and scales them with CSS zoom. @imgMoving and @cropMoving both return an object with a moving boolean and an axis object carrying x1, x2, y1 and y2 for the corners, which is enough to react while the user drags rather than only after they stop. @imgLoad reports success or error.

Export is a callback, not a return value. this.$refs.cropper.getCropData(cb) hands back base64 and getCropBlob(cb) hands back a blob. The instance also exposes cropW and cropH, plus methods including startCrop, stopCrop, clearCrop, changeScale, getImgAxis, getCropAxis, rotateRight and rotateLeft. That set is enough to build a toolbar without touching internals.

Installing vue-cropper and rendering a first crop box

Install with npm or yarn. The README gives both commands, and the package name is vue-cropper in each case.

npm install vue-cropper

For Vue 2, import the component and register it locally. The named export is VueCropper, and the stylesheet lives at dist/index.css.

import { VueCropper } from 'vue-cropper'
import 'vue-cropper/dist/index.css'

export default {
  components: { VueCropper }
}

The README's own usage example binds three props: img, outputSize and outputType. Note the surrounding div. The documentation states the component must be wrapped in an outer container with a width and a height, otherwise the crop box has nothing to size itself against.

<div style="width: 400px; height: 400px">
  <vueCropper
    ref="cropper"
    :img="option.img"
    :outputSize="option.size"
    :outputType="option.outputType"
  ></vueCropper>
</div>

To read the result, call getCropBlob on the ref. The callback receives the cropped blob, which you can append to a FormData and post to your own endpoint.

this.$refs.cropper.getCropBlob(data => {
  const form = new FormData()
  form.append('file', data)
  // post form to your server
})

One warning sits in the README next to this example: turn off your local mock service, because the README states that leaving mock enabled causes file conversion errors. It does not explain the mechanism, only that the cause is unknown to the author.

The Vue 3 story is a redirect, and the version numbers say so

The strongest limitation is not a bug. It is that the README sends Vue 3 users to another project. The Vue 3 instructions here still exist, including a component import, a global app.use(VueCropper) registration and a CDN path through the UMD build, but they sit under a banner telling readers to prefer cropper-next-vue.

The release history supports reading the Vue 3 path as frozen. The latest listed release is 1.1.1 from 2023-11-08, while the @next tag, which is the Vue 3 line, last appears at 2021-08-30. Meanwhile package.json in the repository root declares version 0.6.5, which is the Vue 2 line, and its main field points at ./dist/index.js. If you are starting a Vue 3 project, the honest reading is that you are being pointed at a different library by the maintainer's own documentation.

There are smaller constraints worth knowing before you commit. maxImgSize defaults to 2000, capping the maximum image width and height. The enlarge prop carries an inline caution in the props table against setting it too high. And the README notes that mock services can break file conversion, without a stated cause. None of these are blockers for a straightforward avatar upload, but they are the edges of the box.

Where vue-cropper sits next to Vue-advanced-cropper and Cropper.js

The alternatives people search for alongside this project take different architectural positions. Cropper.js is a framework-agnostic cropper that you instantiate against a DOM element; vue-cropper instead ships a Vue component whose behaviour is configured through props and whose output is read from a component ref. If your application is not Vue, Cropper.js has no framework coupling to work around, and vue-cropper has no use at all.

Vue-advanced-cropper, which appears repeatedly in related searches, is the closer comparison for a Vue codebase. The difference in approach is where the layout logic lives. vue-cropper constrains the crop box relative to a container you size yourself, with props such as fixedBox, centerBox and limitMinSize controlling how the box may move. Vue-advanced-cropper is a separate project with its own API, and this repository's documentation says nothing about it, so the comparison has to be made on the two projects' own docs rather than on any claim made here.

The third path is the one the README itself proposes: cropper-next-vue for Vue 3, which the README describes as supporting rotated-boundary checks, confinement of the image inside the crop box or container, high-DPI export and real-time preview. If you are on Vue 3 and need rotation-aware cropping, that is the direction the maintainer gives you.

Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-03-09. That is a recent push, but it does not by itself tell you which line received attention, and the release list is the more useful signal: 1.1.1 on 2023-11-08 and the @next tag on 2021-08-30. The gap between the two tags is the practical upgrade cost. Moving a Vue 2 integration to the Vue 3 entry point means changing your import to the @next install path, keeping the dist/index.css import, and re-testing every prop you rely on, because the README does not publish a migration table for the change.

Licensing is where the repository is inconsistent in a way worth flagging. The repository metadata and the top-level LICENSE file identify the project as MIT, while package.json declares "license": "ISC". Those are both permissive licences, but they are not the same text. This is a packaging detail rather than a legal position, and it is the kind of thing a compliance review will ask about, so check the LICENSE file in the version you install rather than the metadata field. Nothing here is legal advice.

The build script is a single webpack invocation: rm -rf ./dist && webpack --config webpack.config.js. If you consume the published package rather than building from source, that script never runs on your machine.

Editorial conclusion

Adopt vue-cropper if you maintain a Vue 2 codebase and want a crop box driven by props such as fixed, fixedNumber and centerBox, with export through getCropData or getCropBlob. Do not adopt it for a new Vue 3 project: the README itself recommends cropper-next-vue, and the Vue 3 entry point here is the @next tag, whose most recent release dates from 2021-08-30. Before committing, verify the crop box is wrapped in a sized container, confirm your bundler resolves dist/index.css, and check whether your dev server's mock layer interferes with file conversion, which the README warns about.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xyxiao001/vue-cropper on GitHub