On this page
Overview
Cropper.js is a JavaScript/TypeScript library for building image-cropping interfaces in the browser. A Cropper instance composes custom elements such as <cropper-canvas>, <cropper-image>, and <cropper-selection> to manage selection movement, resizing, and output.
Features and best fit
Based on official documentation; not hands-on tested · Content checked:
Key features
Create a Cropper instance from an image, canvas, or selector
new Cropper(element, options) accepts an HTMLImageElement, HTMLCanvasElement, or selector string. The 既定template includes canvas, image, selection, grid, and handle elements.
Sources: [2]
Control selection position, size, and aspect ratio through element properties
Version 2 represents crop areas as <cropper-selection> elements with properties such as x, y, width, height, and aspectRatio, and it can expose multiple selections.
Convert a selection to Canvas with $toCanvas
The v1 getCroppedCanvas() workflow moves to the <cropper-selection> $toCanvas() method in v2. The application can then choose how to encode, upload, or store the resulting Canvas data.
Sources: [3]
Best fit
Before adoption
Many v1 options and methods moved to custom-element APIs in v2
Options and methods such as viewMode, dragMode, preview, and getCroppedCanvas() were removed or replaced by properties and methods on individual elements, so existing integrations need the migration guide.
Sources: [3]
Cropper.js provides the cropping UI, not the final upload or server-side image pipeline
The crop result is handed back to the application as Canvas-related data; compression, upload destinations, persistence, and server-side image processing remain application responsibilities.
Sources: [2]
Official sources
- [1]Cropper.js v2.2.0 package README(2026-10-05)
- [2]Cropper.js v2.2.0 Cropper API(2026-10-05)
- [3]Cropper.js v2 migration guide(2026-10-05)
- [4]Cropper.js v2.2.0 package metadata(2026-10-05)
- [5]Cropper.js v2.2.0 release(2026-10-05)
Supplemental curator note
Version 2 splits responsibilities across elements such as <cropper-selection> instead of preserving every v1 method. Evaluate migrations with the v2 element APIs in mind—for example, $toCanvas() replaces the old getCroppedCanvas() workflow.
Try it in 3 steps
- 1
Install Cropper.js 2.2.0
Pin the stable v2 release so the example is not mixed with the older v1 API.
npm install --save-exact cropperjs@2.2.0 - 2
Create a Cropper from an image element
Follow the official API by passing the target
HTMLImageElementto theCropperconstructor.import Cropper from 'cropperjs'; const image = document.querySelector('#image'); const cropper = new Cropper(image); - 3
Convert the selection to a Canvas
In v2, use the
<cropper-selection>$toCanvas()method instead of the oldgetCroppedCanvas()API.const selection = cropper.getCropperSelection(); const canvas = await selection?.$toCanvas();
Growth
Growth trends · Last 30 days
13,902 Stars
Trend data is still being collected.
Development activity
Last 90 days · weekly
- Commits (last 30 days)
- 24
- Open PRs
- 0
Development activity is still being collected.
Built with
Categories and tags
Categories
GitHub data
GitHub dataView detailed GitHub data
GitHub Topics
- image-cropper
- image-processing
- cropper
- cropperjs
- javascript
- Stars
- 13,902
- Forks
- 2,431
- Watchers
- 168
- Open issues
- 7
- Contributors
- 44
- Owner type
- User
- Primary language
- TypeScript
- License
- MIT
- Repository last updated
- Oct 4, 2026
Related information
Write a related articleShare a guide or use case for this OSS in Markdown. Articles are published after administrator approval.
Explore next
- SortableJS31,186 Stars
4 shared tag(s)
reorder list items with drag and drop within or across lists while supporting touch input
JavaScript - SweetAlert218,098 Stars
4 shared tag(s)
replace alert, confirm, and prompt dialogs with WAI-ARIA-aware popups that resolve through Promises
JavaScript - Tippy.js12,240 Stars
4 shared tag(s)
position tooltips, popovers, and dropdowns with Popper and attach them to hover, focus, or click interactions
JavaScript - melonJS6,401 Stars
4 shared tag(s)
Build browser-based 2D and 2.5D games through one API across WebGPU, WebGL 2, and Canvas
JavaScript - Motion33,834 Stars
3 shared tag(s) · 1 shared category(s) · Same language
build web animation with gestures, springs, layout transitions, scroll effects, and timelines across React, JavaScript, and Vue
TypeScript - Video.js39,907 Stars
3 shared tag(s) · 1 shared category(s)
add a shared player UI and API to HTML5 video, including web streaming formats such as HLS and DASH
JavaScript
Report incorrect information
Tell us if any listing information is incorrect or outdated.