Author: | fengyuanchen |
---|---|
Views Total: | 23,906 views |
Official Page: | Go to website |
Last Update: | March 1, 2025 |
License: | MIT |
Preview:

Description:
Cropper.js is the Vanilla JavaScript version of the jQuery Image Cropper plugin, which provides feature-rich image cropping functionality for any image.
Main features:
- Touch-friendly.
- Powered by HTML5 canvas.
- Image rotate, zoom, flip, move.
- Extensible and Customizable.
- CSS-in-JS.
- Import on-demand
- Tons of options, methods, and events.
Basic usage (v2):
1. Install & download the Cropper.js library.
# NPM $ npm install cropperjs --save
2. Import Cropper.js into your project.
import Cropper from 'cropperjs';
// OR <script src="https://unpkg.com/cropperjs"></script>
3. Wrap your image or canvas element into a container element.
<div> <img id="image" src="image-to-crop.jpg"> </div>
4. Enable the JavaScript image cropper on the image.
const cropper = new Cropper('#image');
5. Or import all Cropper elements from the cropperjs package and define them as custom elements automatically.
import 'cropperjs';
<cropper-canvas background> <cropper-image src="/path/to/image.jpg" alt="Picture" rotatable scalable skewable translatable></cropper-image> <cropper-shade hidden></cropper-shade> <cropper-handle action="select" plain></cropper-handle> <cropper-selection initial-coverage="0.5" movable resizable> <cropper-grid role="grid" covered></cropper-grid> <cropper-crosshair centered></cropper-crosshair> <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle> <cropper-handle action="n-resize"></cropper-handle> <cropper-handle action="e-resize"></cropper-handle> <cropper-handle action="s-resize"></cropper-handle> <cropper-handle action="w-resize"></cropper-handle> <cropper-handle action="ne-resize"></cropper-handle> <cropper-handle action="nw-resize"></cropper-handle> <cropper-handle action="se-resize"></cropper-handle> <cropper-handle action="sw-resize"></cropper-handle> </cropper-selection> </cropper-canvas>
6. Available options for the Cropper()
.
const cropper = new Cropper('#image',{ container: null, template: ' <cropper-canvas background> <cropper-image></cropper-image> <cropper-shade hidden></cropper-shade> <cropper-handle action="select" plain></cropper-handle> <cropper-selection initial-coverage="0.5" movable resizable> <cropper-grid role="grid" bordered covered></cropper-grid> <cropper-crosshair centered></cropper-crosshair> <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle> <cropper-handle action="n-resize"></cropper-handle> <cropper-handle action="e-resize"></cropper-handle> <cropper-handle action="s-resize"></cropper-handle> <cropper-handle action="w-resize"></cropper-handle> <cropper-handle action="ne-resize"></cropper-handle> <cropper-handle action="nw-resize"></cropper-handle> <cropper-handle action="se-resize"></cropper-handle> <cropper-handle action="sw-resize"></cropper-handle> </cropper-selection> </cropper-canvas>' });
7. API methods.
// Get the <cropper-canvas> element in the Cropper container. cropper.getCropperCanvas() // Get the <cropper-image> element in the Cropper container. cropper.getCropperImage(); // Get the <cropper-selection> element in the Cropper container. cropper.getCropperSelection(); // Get all the <cropper-selection> elements in the Cropper container when there are multiple selections. cropper.getCropperSelections()
8. Check out the official website for full DOCs.
Changelog:
v2.0.0 (03/01/2025)
- Refactor and bugfix
v1.6.1 (09/17/2023)
- Bugfixes
v1.6.0 (08/26/2023)
- Add a rounded option to the getCroppedCanvas method
v1.5.13 (11/20/2021)
- Add backface-visibility: hidden to the cropper image to avoid ghost lines when moving
- Remove useless cropper-hide class from cropper image.
- Check whether the parent node exists or not before removing the cropper container.
v1.5.12 (06/12/2021)
- Fix the cropper responsive when only the height was changed
v1.5.11 (02/17/2021)
- Fix TypeScript declarations compatibility
v1.5.10 (02/14/2021)
- Explicitly set the XMLHttpRequest request to be asynchronous
- Improve TypeScript declarations
v1.5.6 (10/29/2019)
- improve event type determining for iOS 13+