vue-img-cutter: an image cropper for Vue with rotate, zoom and fixed ratios

A cropper you configure rather than build

vue-img-cutter is described as an image crop plug-in for Vue, and you can use it to rotate, zoom images and cut any size. The Chinese description in the project metadata spells out the same feature set in more detail: moving the image, cropping it, zooming in and out, moving the selection up, down, left and right, a fixed ratio, a fixed size, cropping a remote image, all with very little code, and all adjustable through parameters to fit your own business needs.

That last clause is the design position of the project. A cropper is one of those components that every application ends up needing and few want to write, because the canvas work, the coordinate mapping between the displayed image and the original pixels, and the drag interactions are all fiddly and all similar between projects. So the component is a set of behaviours you switch on, and the parameter table is the interface.

The browser support claim is worth reading as what it is, a statement about the project vintage rather than a recommendation. The feature list says it works for IE9+, MSEdge, Chrome and Firefox. IE9 is mentioned again later, where a separate method is offered for compatibility with it. The plugin has clearly been kept working across a long span of browsers, but that is history rather than a target for a new project.

The library is MIT licensed and published on npm as vue-img-cutter, with the homepage at acccccccb.github.io/vue-img-cutter and a Chinese documentation file, README-zh-CN.md, alongside the English one. The repository is also mirrored on Gitee, and the author asks for a star if the project is helpful. The releases are v3.1.1 from 2026-05-06, 3.1.0 from 2026-05-05 and v3.0.7 from 2025-03-17.

Two packages, because Vue 2 and Vue 3 are not the same target

The installation step is the first place a new user has to make a decision, and the instructions spell out both branches:

npm install vue-img-cutter@2 --save-dev # for vue2
npm install vue-img-cutter@3 --save-dev # for vue3 + vite + typescript

The major version of the package is what selects the Vue generation, not a peer dependency range. The Vue 3 line is the one that mentions Vite and TypeScript, which matches the tooling in the repository itself, where the package manifest lists vite, typescript and vite-plugin-dts in the dev dependencies and the source is built with Vite.

The package manifest also shows the shape of the published artefact, which matters if you are bundling it. The main field points at a UMD build, the module field at an ES module build, and the exports map has types, import and require conditions, so a TypeScript project gets the declaration file and a bundler gets the ES build. There is a separate export entry for the stylesheet at `./vue-img-cutter.css`, which is why the import instructions include the CSS as its own line.

The runtime dependencies are small: core-js, vue and vue-i18n. The last of those is the interesting one, because it means the component ships with translations rather than hardcoded strings. That fits with the parameter table, where the modal title and the button label have Chinese defaults, which a translation layer then localises.

The engine requirement is stated in the manifest as Node 22.22.2 or newer, and the declared Vue dependency is 3.5 or newer. So a project on an older Node or an older Vue 3 will not install the current line cleanly.

Using it as a modal, inline, or through a ref

There are three usage shapes in the documentation, and they cover quite different applications.

The first is the plain component. You import it and register it as a component, then put it in the template:

import ImgCutter from 'vue-img-cutter'
import 'vue-img-cutter/vue-img-cutter.css'
export default {
        components:{
            ImgCutter
        },
...
}

and then:

<ImgCutter v-on:cutDown="cutDown"></ImgCutter>

The event is cutDown, and the handler receives the cropped result. The CSS import is separate from the component import because the stylesheet ships as its own export, which is what lets a project override or bundle it separately.

The second shape adds a slot for the trigger button, which is how you replace the default button with your own markup:

<ImgCutter v-on:cutDown="cutDown">
    <template #open>
        <button>Choose image</button>
    </template>
</ImgCutter>

The named slot is `open`, and the default inside it is a button labelled with the label parameter, which defaults to the Chinese text for choose image. Replacing it lets the trigger live wherever it fits your layout.

The third shape is the imperative one, reached through a ref. The documentation presents it as the method to be compatible with IE9, and it can also be used to crop cross domain images:

ForIE9:function(){
	// First you need create object have name,src.
	// Then trigger handleOpen(obj) and deliver the obj.
	this.$refs.imgCutterModal.handleOpen({
        name:"image.jpg",
        src:"http://imageServ.com/image.jpg",
    });
}

and the object it takes is described in the earlier snippet:

// The object like this.
let obj = {
    name: '1.jpg', //Image name
    src: 'http://url/1.jpg', // Image url
    //width:200,//Image width  remove in 2.1.9+
    //height:200,//Image height remove in 2.1.9+
};

The commented-out width and height lines carry a version note: they were removed in 2.1.9 and up. That is a small but instructive detail, since it tells you the object shape changed and that the current object needs only a name and a source.

Because the imperative path requires a ref to a specific component instance, it is the shape that also gives you programmatic control over which image is loaded and when, which is what makes it usable for a remote image the user has picked elsewhere in the application.

The parameter table is the real interface

The attribute table is the most useful part of the documentation, and it is worth reading as a description of the feature set rather than as a list of props.

The layout is controlled by a small group. `isModal` decides whether the tool appears as a modal or inline, defaulting to true, and `showChooseBtn` decides whether the select button is shown, also defaulting to true. `lockScroll` locks page scrolling while the modal is open, again defaulting to true, and `modalTitle` sets the title text with a Chinese default. `label` is the button text, with a Chinese default.

Then the geometry. `boxWidth` is the tool width with a default of 800 and `boxHeight` the tool height with a default of 400, so the cropper itself is 800 by 400 pixels unless you say otherwise. `cutWidth` and `cutHeight` are the selection box size, both defaulting to 200, which means the default crop is a 200 by 200 square inside an 800 by 400 tool.

The behaviour switches are `tool`, which shows the toolbar and defaults to true, `sizeChange` for allowing the selection box to be resized and `moveAble` for allowing the image to be moved, both defaulting to true. `rate` sets an aspect ratio in the form of a string such as "4:3", with a default of a dash meaning none. `originalGraph` decides whether the original image or the cropped result is emitted, and it defaults to false.

The cross-origin pair is `crossOrigin`, a boolean defaulting to false, and `crossOriginHeader`, a string defaulting to an empty string. Those two together are how you crop an image from another origin, which requires the server to send the right header, and the earlier note that the imperative method can also be used to crop cross domain images points at the same feature.

The watermark group is a separate cluster. `WatermarkText` sets the text, `WatermarkTextFont` the font size with a default of 12px Sans-serif, `WatermarkTextColor` the colour with a default of white, `WatermarkTextX` and a matching Y coordinate for the position, with the X default shown as 0.95. So the watermark is positioned by ratio rather than by pixels, which is what lets it sit at a relative spot on an image of any size.

Notice the capitalisation in the watermark attribute names against the lower case elsewhere. That inconsistency is in the documented interface, and it matters to anyone writing against it, since Vue attributes are matched case-insensitively in in-DOM templates but not in single file components.

How the project is built and what ships in the package

The repository layout shows a modern Vue component library with a documentation site built from the same source.

There is a `src/` directory holding the component and the application code, a `public/` and a `static/` directory for assets, and an `index.html` at the root, which is the entry point Vite serves in development. `vite.config.ts` is the build configuration, and `tsconfig.json` the TypeScript one. The linting and formatting setup is a `eslint.config.js` for flat config ESLint, a `.prettierrc` and a `.editorconfig`, with `.gitignore` and `.npmignore` keeping the right things out of version control and out of the tarball. `_config.yml` is a configuration file for the GitHub Pages site.

The build scripts in the package manifest are the interesting part. `dev` runs Vite, `build` runs a production build, `build:page` builds with the page mode, and `preview` serves the built output. The lint script runs ESLint with `--fix` across the Vue, JavaScript and TypeScript extensions, which tells you the author expects formatting to be corrected automatically rather than argued about.

The development dependencies describe the tooling precisely. There is the Vite plugin for Vue, TypeScript itself and the TypeScript ESLint parser, the Vue ESLint parser and the Vue TypeScript language core, Prettier with its ESLint plugin and config, `vite-plugin-dts` for generating the declaration file, `vite-plugin-eslint` to run the linter as part of the build, and `@microsoft/api-extractor` for the API surface. The last two are the choices that keep a published component honest, since the declaration file and the exported types are part of what consumers see.

Only the `dist` directory is published, which is the standard arrangement and means the repository source and the npm tarball are separate artefacts. The Vue and vue-i18n versions in the dependencies, Vue at 3.5 and vue-i18n at 11.4, also tell you that the current line is built for the Vue 3 generation, with the Vue 2 package being the older major version kept for existing projects.

The topic tags are copper, image, vue and vue-img-cutter, and the last push was on 2026-05-06, the same day as the v3.1.1 release.

Editorial conclusion

Adopt vue-img-cutter if you need a cropper inside a Vue application and want the rotation, zoom and fixed-ratio behaviour configured rather than hand-built. Do not adopt it if you need to crop very large images on the client with tight memory limits, since the cropping happens in the browser against a canvas, and check first which major version you install, because the Vue 2 and Vue 3 lines are separate packages with different major version numbers on npm.

Frequently asked questions

Official sources

1. acccccccb/vue-img-cutter on GitHub
2. License: MIT
3. Project website
4. README
5. Releases