# Cropper.js v2: a JavaScript image cropper built from web components

> Cropper.js is an MIT-licensed image cropper for the browser, and v2 rebuilds it around custom elements with a separate element for the crop box. This is what the repository documents, where the design costs you, and what the v1 and v2 split means for adoption.

**fengyuanchen/cropperjs** — JavaScript image cropper.

- Repository: https://github.com/fengyuanchen/cropperjs
- Website: https://fengyuanchen.github.io/cropperjs/
- Stars: 13,901 · Forks: 2,433
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/fengyuanchen-cropperjs

## The browser-side crop step that Cropper.js owns

Cropping an uploaded photo means two different jobs. One is letting a person frame the area they want. The other is producing pixels. Cropper.js takes the first job and leaves the second to you. It renders an image inside a crop viewport, gives the user a draggable selection with handles, and exposes the resulting rectangle so your code can read the coordinates and do whatever comes next: send them to a server, draw to a canvas, or preview a thumbnail. The README describes the project in one line as a "JavaScript image cropper", and the topics attached to the repository are cropper, cropperjs, image-cropper, image-processing and javascript. That is the whole scope. It is for front-end engineers building an avatar uploader, a banner editor, a document scanner UI, or any form where the user has to choose a region of a picture before it is stored. If your application already hands the file to a backend and the backend decides the crop, this library is not part of that path.

## Why v2 is a set of custom elements and not a single container

Version 1 wrapped everything in one element: you pointed it at an image and it drew the crop box itself. Version 2 changes the composition. The repository ships a packages/ directory with a lerna.json and a workspaces field in the root package.json, so v2 is a set of packages rather than one bundle, and the user-facing pieces are custom elements. The README states plainly that this is "the branch for v2.x" and points at a v1 branch for the older line. The practical consequence is that cropping is assembled from parts: a canvas element holds the image, and a selection element defines the movable crop area. That is a real architectural difference, not a rename. It lets you place the selection differently, style the handles through CSS, and compose the pieces yourself. It also means the single-element mental model from v1 tutorials does not transfer. The README does not spell out the full element set or the event names; for those, the documentation site at fengyuanchen.github.io/cropperjs is the reference the repository links to. The root package.json is marked "private": true with workspaces, which is the signature of a monorepo root rather than the published package, so the thing you install is a workspace package, not this manifest.

## What the repository tells you before you install Cropper.js

The README is short. It names the package's purpose, points at the v1 branch, links the documentation site, and lists related wrapper projects. It does not contain an install walkthrough, a usage snippet, or a list of element attributes, so there is no code from the repository to quote here, and inventing one would be worse than leaving it out. What the repository files do establish is the shape of the distribution. The root package.json is named cropperjs at version 2.2.0 and is marked "private": true, with a workspaces field pointing at packages/*. That means the publishable artifacts live under packages/ and are released through lerna with the publish script. For an adopter, the practical reading is that the npm package name is cropperjs and the source you read on GitHub is the monorepo root, not a one-to-one match for what lands in node_modules. The documentation site linked from the README is where the element names, attributes and events are described. Confirm the setup there before writing integration code, because the README will not correct you.

## The v1 and v2 split is the sharpest edge in this project

Two lines are maintained at once. The releases list shows v2.2.0 and v1.6.3 published on the same day, 2026-08-23, and v2.1.1 earlier in the year. That is deliberate support for the old line, and it is also the most likely way to get confused. If you follow a blog post written for v1 and install the current package, the API you were shown will not be there, because the v1 code lives on a separate branch. The README gives no migration guide and no compatibility shim; it only states which branch is which. A second limitation is scope. Cropper.js produces a selection rectangle, not a cropped file. There is no documented server-side rendering path, no batch processing, and no headless mode for cropping images in a build step. If your requirement is "crop ten thousand images on a schedule", this is the wrong tool and always will be. A third edge is the wrapper ecosystem. The README lists related projects including react-cropper, vue-cropperjs, angular-cropperjs, ember-cropperjs and blazor-cropperjs, and it flags exactly one of them, cropperjs-react-wrapper, as "compatible with v2". That note is the signal: most of those wrappers were written against v1, and pairing one with the v2 package is a mismatch you will discover at runtime.

## Cropper.js against a canvas-only or server-side approach

The obvious alternative is to skip the library and write the interaction on a plain canvas element. That gives you total control and no dependency, and for a fixed rectangle with no resize handles it is genuinely less code. The difference appears the moment you need the interaction details users expect: dragging the selection, resizing from handles, keeping the box inside the image bounds, and mapping screen coordinates to source-image coordinates when the picture is displayed at a different scale than its natural size. Cropper.js has already solved that mapping and the boundary behaviour. Hand-rolling it means reimplementing those rules and maintaining them. The other alternative is a server-side cropper, where the browser only sends coordinates and an image library does the work. That is a better fit when the source image must never reach the client at full resolution, or when the same crop has to be reproduced consistently outside the browser. Cropper.js cannot help there. The honest split is this: use Cropper.js when the crop is interactive and the pixels can be produced client-side; use a server-side library when the crop is a pipeline step. They are not substitutes.

## Maintenance, versioning and what the MIT licence leaves you

The repository is not archived and the last push was on 2026-09-13, so the project is being worked on. It follows Semantic Versioning according to the README, and commits follow Conventional Commits, with a changelog script driven by conventional-changelog. That matters for upgrade cost: the project states its versioning policy, and the CHANGELOG.md at the repository root is the place the release notes are generated into. The same-day v1.6.3 and v2.2.0 releases mean a v1 user can still take patch fixes without moving to the new element model. Budget for the v2 migration as a rewrite of your integration layer, not a version bump, because the composition changed. The licence is MIT, held by Chen Fengyuan. MIT is permissive: it allows commercial use, modification and redistribution with the licence and copyright notice retained. That is a summary of the licence identifier, not legal advice, and if your organisation has rules about attribution in bundled front-end assets, run the actual text past whoever handles that.

## Conclusion

Adopt Cropper.js when you need in-browser cropping and want a maintained MIT library rather than a service: the last push was 2026-09-13 and v2.2.0 shipped on 2026-08-23. Do not adopt it if you need server-side cropping, a framework-native component, or a v1 API you cannot migrate, because v2 lives on a separate branch with a different element structure. Before committing, verify which branch your dependency resolves to, confirm the wrapper you plan to use is the v2-compatible one, and check the documentation site for the element attributes your integration depends on.

## FAQ

### How do I use Cropper.js in a project?

The README does not include a usage walkthrough, so the starting point is the documentation site it links to at fengyuanchen.github.io/cropperjs. The package is published as cropperjs, and the repository root is a private monorepo manifest with workspaces, so the published artifacts come from the packages/ directory.

### What is Cropper.js?

It is a JavaScript image cropper, described that way in its own README, distributed under the MIT licence. Version 2 is built from custom elements, with a canvas element for the image and a selection element for the crop box. Version 1 lives on a separate branch with a different API.

### What are Cropper.js alternatives?

The README does not name competing libraries. The realistic alternatives are writing the crop interaction yourself on a canvas element, which means handling drag, resize and coordinate mapping, or moving the crop to a server-side image library so the browser only sends coordinates.

### Which image cropper is easiest to use?

The README does not compare Cropper.js with other croppers, so it cannot answer that. What it does document is the scope: a JavaScript image cropper under the MIT licence, with a v2 branch built from custom elements and a v1 branch for the older API.

### How can I crop an image in JavaScript?

Cropper.js handles the selection side in the browser: it renders the image in a crop viewport and lets the user drag and resize a crop box. Producing the cropped pixels from that selection is code you write, since the library exposes the rectangle rather than an output file.

## Sources

- [fengyuanchen/cropperjs on GitHub](https://github.com/fengyuanchen/cropperjs)
- [License: MIT](https://github.com/fengyuanchen/cropperjs/blob/main/LICENSE)
- [Project website](https://fengyuanchen.github.io/cropperjs/)
- [README](https://github.com/fengyuanchen/cropperjs/blob/main/README.md)
- [Releases](https://github.com/fengyuanchen/cropperjs/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fengyuanchen-cropperjs