# cropperjs
**Repository Path**: mirrors_fis-components/cropperjs
## Basic Information
- **Project Name**: cropperjs
- **Description**: Fork from https://github.com/fengyuanchen/cropperjs.git
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2026-10-21
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Cropper.js
> JavaScript image cropper.
- [Homepage](http://cropperjs.com)
- [Cropper as jQuery plugin](https://github.com/fengyuanchen/cropper)
- [Photo Editor](http://fengyuanchen.github.io/photo-editor) - An advanced example of Cropper.js.
[](https://travis-ci.org/fengyuanchen/cropperjs)
## Table of contents
- [Features](#features)
- [Main](#main)
- [Getting started](#getting-started)
- [Options](#options)
- [Methods](#methods)
- [No conflict](#no-conflict)
- [Browser support](#browser-support)
- [Contributing](#contributing)
- [Versioning](#versioning)
- [License](#license)
## Features
- Supports 39 [options](#options) (includes 7 callbacks)
- Supports 27 [methods](#methods)
- Supports touch (mobile)
- Supports zooming
- Supports rotating
- Supports scaling (flipping)
- Supports multiple croppers
- Supports to crop on a canvas
- Supports to crop image in the browser-side by canvas
- Supports to translate Exif Orientation information
- Cross-browser support
## Main
```
dist/
├── cropper.css ( 5 KB)
├── cropper.min.css ( 4 KB)
├── cropper.js (88 KB)
└── cropper.min.js (28 KB)
```
## Getting started
### Quick start
Four quick start options are available:
- [Download the latest release](https://github.com/fengyuanchen/cropperjs/archive/master.zip).
- Clone the repository: `git clone https://github.com/fengyuanchen/cropperjs.git`.
- Install with [NPM](http://npmjs.org): `npm install cropperjs`.
- Install with [Bower](http://bower.io): `bower install cropperjs`.
### Installation
Include files:
```html
```
### Usage
Initialize with `Cropper` constructor:
- Browser: `window.Cropper`
- CommonJS: `var Cropper = require('cropper')`
- NodeJS: `var Cropper = require('cropperjs')(window)`
```html
```
```js
var image = document.getElementById('image');
var cropper = new Cropper(image, {
aspectRatio: 16 / 9,
crop: function(data) {
console.log(data.x);
console.log(data.y);
console.log(data.width);
console.log(data.height);
console.log(data.rotate);
console.log(data.scaleX);
console.log(data.scaleY);
}
});
```
#### FAQ
See the [FAQ](FAQ.md) documentation.
#### Notes
- The size of the cropper inherits from the size of the image's parent element (wrapper), so be sure to wrap the image with a **visible block element**.
- The outputted cropped data bases on the original image size, so you can use them to crop the image directly.
- If you try to start cropper on a cross-origin image, please make sure that your browser supports HTML5 [CORS settings attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes), and your image server supports the `Access-Control-Allow-Origin` option (see the [HTTP access control (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS)).
#### Known issues
- [Known iOS resource limits](https://developer.apple.com/library/mac/documentation/AppleApplications/Reference/SafariWebContent/CreatingContentforSafarioniPhone/CreatingContentforSafarioniPhone.html): As iOS devices limit memory, the browser may crash when you are cropping a large image (iPhone camera resolution). To avoid this, you may resize the image first (preferably below 1024 pixels) before start a cropper.
[⬆ back to top](#table-of-contents)
## Options
You may set cropper options with `new Cropper(image, options)`.
If you want to change the global default options, You may use `Cropper.setDefaults(options)`.
### viewMode
- Type: `Number`
- Default: `0`
- Options:
- `0`: the crop box is just within the container
- `1`: the crop box should be within the canvas
- `2`: the canvas should not be within the container
- `3`: the container should be within the canvas
Define the view mode of the cropper.
### dragMode
- Type: `String`
- Default: `'crop'`
- Options:
- `'crop'`: create a new crop box
- `'move'`: move the canvas
- `'none'`: do nothing
Define the dragging mode of the cropper.
### aspectRatio
- Type: `Number`
- Default: `NaN`
Set the aspect ratio of the crop box. By default, the crop box is free ratio.
### data
- Type: `Object`
- Default: `null`
The previous cropped data if you had stored, will be passed to `setData` method automatically when built.
### preview
- Type: `String`
- Default: `''`
- A valid selector for [Document.querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll)
Add extra elements (containers) for previewing.
**Notes:**
- The maximum width is the initial width of preview container.
- The maximum height is the initial height of preview container.
- If you set an `aspectRatio` option, be sure to set the same aspect ratio to the preview container.
- If preview is not getting properly displayed, set `overflow: hidden` style to the preview container.
### responsive
- Type: `Boolean`
- Default: `true`
Re-render the cropper when resize the window.
### restore
- Type: `Boolean`
- Default: `true`
Restore the cropped area after resize the window.
### checkCrossOrigin
- Type: `Boolean`
- Default: `true`
Check if the current image is a cross-origin image.
If it is, when clone the image, a `crossOrigin` attribute will be added to the cloned image element and a timestamp will be added to the `src` attribute to reload the source image to avoid browser cache error.
By adding `crossOrigin` attribute to image will stop adding timestamp to image url, and stop reload of image.
### checkOrientation
- Type: `Boolean`
- Default: `true`
Check the current image's Exif Orientation information.
More exactly, read the Orientation value for rotating or flipping the image, and then override the Orientation value with `1` (the default value) to avoid some issues ([1](https://github.com/fengyuanchen/cropper/issues/120), [2](https://github.com/fengyuanchen/cropper/issues/509)) on iOS devices.
> Requires [Typed Arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) support ([IE 10+](http://caniuse.com/typedarrays)).
### modal
- Type: `Boolean`
- Default: `true`
Show the black modal above the image and under the crop box.
### guides
- Type: `Boolean`
- Default: `true`
Show the dashed lines above the crop box.
### center
- Type: `Boolean`
- Default: `true`
Show the center indicator above the crop box.
### highlight
- Type: `Boolean`
- Default: `true`
Show the white modal above the crop box (highlight the crop box).
### background
- Type: `Boolean`
- Default: `true`
Show the grid background of the container.
### autoCrop
- Type: `Boolean`
- Default: `true`
Enable to crop the image automatically when initialize.
### autoCropArea
- Type: `Number`
- Default: `0.8` (80% of the image)
A number between 0 and 1. Define the automatic cropping area size (percentage).
### movable
- Type: `Boolean`
- Default: `true`
Enable to move the image.
### rotatable
- Type: `Boolean`
- Default: `true`
Enable to rotate the image.
### scalable
- Type: `Boolean`
- Default: `true`
Enable to scale the image.
### zoomable
- Type: `Boolean`
- Default: `true`
Enable to zoom the image.
### zoomOnTouch
- Type: `Boolean`
- Default: `true`
Enable to zoom the image by dragging touch.
### zoomOnWheel
- Type: `Boolean`
- Default: `true`
Enable to zoom the image by wheeling mouse.
### wheelZoomRatio
- Type: `Number`
- Default: `0.1`
Define zoom ratio when zoom the image by wheeling mouse.
### cropBoxMovable
- Type: `Boolean`
- Default: `true`
Enable to move the crop box.
### cropBoxResizable
- Type: `Boolean`
- Default: `true`
Enable to resize the crop box.
### toggleDragModeOnDblclick
- Type: `Boolean`
- Default: `true`
Enable to toggle drag mode between "crop" and "move" when click twice on the cropper.
### minContainerWidth
- Type: `Number`
- Default: `200`
The minimum width of the container.
### minContainerHeight
- Type: `Number`
- Default: `100`
The minimum height of the container.
### minCanvasWidth
- Type: `Number`
- Default: `0`
The minimum width of the canvas (image wrapper).
### minCanvasHeight
- Type: `Number`
- Default: `0`
The minimum height of the canvas (image wrapper).
### minCropBoxWidth
- Type: `Number`
- Default: `0`
The minimum width of the crop box.
### minCropBoxHeight
- Type: `Number`
- Default: `0`
The minimum height of the crop box.
### build
- Type: `Function`
- Default: `null`
This function will be called when a cropper instance starts to load an image.
> Return `false` to prevent to build.
### built
- Type: `Function`
- Default: `null`
This function will be called when a cropper instance has built completely.
```js
var cropper = new Cropper(image, {
built: function () {
console.log(this.cropper === cropper); // true
}
});
```
### cropstart
- Type: `Function`
- Default: `null`
- (argument):
- Type: `Object`
- Properties:
- `originalEvent`:
- Type: `Event`
- Options: `mousedown`, `touchstart` and `pointerdown`
- `action`:
- Type: `String`
- Options:
- `'crop'`: create a new crop box
- `'move'`: move the canvas (image wrapper)
- `'zoom'`: zoom in / out the canvas (image wrapper) by touch.
- `'e'`: resize the east side of the crop box
- `'w'`: resize the west side of the crop box
- `'s'`: resize the south side of the crop box
- `'n'`: resize the north side of the crop box
- `'se'`: resize the southeast side of the crop box
- `'sw'`: resize the southwest side of the crop box
- `'ne'`: resize the northeast side of the crop box
- `'nw'`: resize the northwest side of the crop box
- `'all'`: move the crop box (all directions)
This function will be called when the canvas (image wrapper) or the crop box starts to change.
> Return `false` to prevent to start.
```js
new Cropper(image, {
cropstart: function (data) {
console.log(data.originalEvent);
console.log(data.action);
}
});
```
### cropmove
- Type: `Function`
- Default: `null`
- (argument):
- Type: `Object`
- Properties:
- `originalEvent`:
- Type: `Event`
- Options: `mousemove`, `touchmove` and `pointermove`.
- `action`: the same as "cropstart".
This function will be called when the canvas (image wrapper) or the crop box is changing.
> Return `false` to prevent to move.
### cropend
- Type: `Function`
- Default: `null`
- (argument):
- Type: `Object`
- Properties:
- `originalEvent`:
- Type: `Event`
- Options: `mouseup`, `touchend`, `touchcancel`, `pointerup` and `pointercancel`.
- `action`: the same as "cropstart".
This function will be called when the canvas (image wrapper) or the crop box stops to change.
### crop
- Type: `Function`
- Default: `null`
- (argument):
- Type: `Object`
- Properties: See the [`getData`](#getdatarounded) method.
This function will be called when the canvas (image wrapper) or the crop box changed.
### zoom
- Type: `Function`
- Default: `null`
- (argument):
- Type: `Object`
- Properties:
- `originalEvent`:
- Type: `Event`
- Options: `wheel`, `touchmove`.
- `oldRatio`:
- Type: `Number`
- The old (current) ratio of the canvas
- `ratio`:
- Type: `Number`
- The new (next) ratio of the canvas (`canvasData.width / canvasData.naturalWidth`)
This function will be called when a cropper instance starts to zoom in or zoom out its canvas (image wrapper).
> Return `false` to prevent to zoom.
```js
new Cropper(image, {
zoom: function (data) {
// Zoom in
if (data.ratio > data.oldRatio) {
return false; // Prevent zoom in
}
// Zoom out
// ...
}
});
```
[⬆ back to top](#table-of-contents)
## Methods
As there is an **asynchronous** process when load the image, you **should call most of the methods after built**, except "setAspectRatio", "replace" and "destroy".
> If a method doesn't need to return any value, it will return the cropper instance (`this`) for chain composition.
```js
new Cropper(image, {
built: function () {
// this.cropper[method](argument1, , argument2, ..., argumentN);
this.cropper.move(1, -1);
// Allows chain composition
this.cropper.move(1, -1).roate(45).scale(1, -1);
}
});
```
### crop()
Show the crop box manually.
```js
new Cropper(image, {
autoCrop: false,
built: function () {
// Do something here
// ...
// And then
this.cropper.crop();
}
});
```
### reset()
Reset the image and crop box to their initial states.
### clear()
Clear the crop box.
### replace(url)
- **url**:
- Type: `String`
- A new image url.
Replace the image's src and rebuild the cropper.
### enable()
Enable (unfreeze) the cropper.
### disable()
Disable (freeze) the cropper.
### destroy()
Destroy the cropper and remove the instance from the image.
### move(offsetX[, offsetY])
- **offsetX**:
- Type: `Number`
- Moving size (px) in the horizontal direction.
- **offsetY** (optional):
- Type: `Number`
- Moving size (px) in the vertical direction.
- If not present, its default value is `offsetX`.
Move the canvas (image wrapper) with relative offsets.
```js
cropper.move(1);
cropper.move(1, 0);
cropper.move(0, -1);
```
### moveTo(x[, y])
- **x**:
- Type: `Number`
- The `left` value of the canvas
- **y** (optional):
- Type: `Number`
- The `top` value of the canvas
- If not present, its default value is `x`.
Move the canvas (image wrapper) to an absolute point.
### zoom(ratio)
- **ratio**:
- Type: `Number`
- Zoom in: requires a positive number (ratio > 0)
- Zoom out: requires a negative number (ratio < 0)
Zoom the canvas (image wrapper) with a relative ratio.
```js
cropper.zoom(0.1);
cropper.zoom(-0.1);
```
### zoomTo(ratio)
- **ratio**:
- Type: `Number`
Zoom the canvas (image wrapper) to an absolute ratio.
```js
cropper.zoomTo(1); // 1:1 (canvasData.width === canvasData.naturalWidth)
```
### rotate(degree)
- **degree**:
- Type: `Number`
- Rotate right: requires a positive number (degree > 0)
- Rotate left: requires a negative number (degree < 0)
Rotate the canvas (image wrapper) with a relative degree.
> Requires [CSS3 2D Transforms](https://developer.mozilla.org/en-US/docs/Web/CSS/transform) support ([IE 9+](http://caniuse.com/transforms2d)).
```js
cropper.rotate(90);
cropper.rotate(-90);
```
### rotateTo(degree)
- **degree**:
- Type: `Number`
Rotate the canvas (image wrapper) to an absolute degree.
### scale(scaleX[, scaleY])
- **scaleX**:
- Type: `Number`
- Default: `1`
- The scaling factor to apply on the abscissa of the image.
- When equal to `1` it does nothing.
- **scaleY** (optional):
- Type: `Number`
- The scaling factor to apply on the ordinate of the image.
- If not present, its default value is `scaleX`.
Scale the image.
> Requires [CSS3 2D Transforms](https://developer.mozilla.org/en-US/docs/Web/CSS/transform) support ([IE 9+](http://caniuse.com/transforms2d)).
```js
cropper.scale(-1); // Flip both horizontal and vertical
cropper.scale(-1, 1); // Flip horizontal
cropper.scale(1, -1); // Flip vertical
```
### scaleX(scaleX)
- **scaleX**:
- Type: `Number`
- Default: `1`
- The scaling factor to apply on the abscissa of the image.
- When equal to `1` it does nothing.
Scale the abscissa of the image.
### scaleY(scaleY)
- **scaleY**:
- Type: `Number`
- Default: `1`
- The scaling factor to apply on the ordinate of the image.
- When equal to `1` it does nothing.
Scale the ordinate of the image.
### getData([rounded])
- **rounded** (optional):
- Type: `Boolean`
- Default: `false`
- Set `true` to get rounded values.
- (return value):
- Type: `Object`
- Properties:
- `x`: the offset left of the cropped area
- `y`: the offset top of the cropped area
- `width`: the width of the cropped area
- `height`: the height of the cropped area
- `rotate`: the rotated degrees of the image
- `scaleX`: the scaling factor to apply on the abscissa of the image
- `scaleY`: the scaling factor to apply on the ordinate of the image
Output the cropped area position and size data (base on the original image).

### setData(data)
- **data**:
- Type: `Object`
- Properties: See the [`getData`](#getdatarounded) method.
Change the cropped area position and size with new data (base on the original image).
**Note:** Only available in strict mode.
### getContainerData()
- (return value):
- Type: `Object`
- Properties:
- `width`: the current width of the container
- `height`: the current height of the container
Output the container size data.

### getImageData()
- (return value):
- Type: `Object`
- Properties:
- `left`: the offset left of the image
- `top`: the offset top of the image
- `width`: the width of the image
- `height`: the height of the image
- `naturalWidth`: the natural width of the image
- `naturalHeight`: the natural height of the image
- `aspectRatio`: the aspect ratio of the image
- `rotate`: the rotated degrees of the image if rotated
- `scaleX`: the scaling factor to apply on the abscissa of the image if scaled
- `scaleY`: the scaling factor to apply on the ordinate of the image if scaled
Output the image position, size and other related data.
### getCanvasData()
- (return value):
- Type: `Object`
- Properties:
- `left`: the offset left of the canvas
- `top`: the offset top of the canvas
- `width`: the width of the canvas
- `height`: the height of the canvas
- `naturalWidth`: the natural width of the canvas (read only)
- `naturalHeight`: the natural height of the canvas (read only)
Output the canvas (image wrapper) position and size data.
```js
var imageData = cropper.getImageData();
var canvasData = cropper.getCanvasData();
if (imageData.rotate % 180 === 0) {
console.log(canvasData.naturalWidth === imageData.naturalWidth); // true
}
```
### setCanvasData(data)
- **data**:
- Type: `Object`
- Properties:
- `left`: the new offset left of the canvas
- `top`: the new offset top of the canvas
- `width`: the new width of the canvas
- `height`: the new height of the canvas
Change the canvas (image wrapper) position and size with new data.
### getCropBoxData()
- (return value):
- Type: `Object`
- Properties:
- `left`: the offset left of the crop box
- `top`: the offset top of the crop box
- `width`: the width of the crop box
- `height`: the height of the crop box
Output the crop box position and size data.
### setCropBoxData(data)
- **data**:
- Type: `Object`
- Properties:
- `left`: the new offset left of the crop box
- `top`: the new offset top of the crop box
- `width`: the new width of the crop box
- `height`: the new height of the crop box
Change the crop box position and size with new data.
### getCroppedCanvas([options])
- **options** (optional):
- Type: `Object`
- Properties:
- `width`: the destination width of the output canvas
- `height`: the destination height of the output canvas
- `fillColor`: a color to fill any alpha values in the output canvas
- (return value):
- Type: `HTMLCanvasElement`
- A canvas drawn the cropped image.
- Browser support:
- Basic image: requires [Canvas](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) support ([IE 9+](http://caniuse.com/canvas)).
- Rotated image: requires [CSS3 2D Transforms](https://developer.mozilla.org/en-US/docs/Web/CSS/transform) support ([IE 9+](http://caniuse.com/transforms2d)).
- Cross-origin image: requires HTML5 [CORS settings attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) support ([IE 11+](http://caniuse.com/cors)).
Get a canvas drawn the cropped image.
> After then, you can display the canvas as an image directly, or use [canvas.toDataURL](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL) to get a Data URL, or use [canvas.toBlob](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob) to get a blob and upload it to server with [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) if the browser supports these APIs.
```js
cropper.getCroppedCanvas();
cropper.getCroppedCanvas({
width: 160,
height: 90
});
// Upload cropped image to server if the browser supports `canvas.toBlob`
cropper.getCroppedCanvas().toBlob(function (blob) {
var formData = new FormData();
formData.append('croppedImage', blob);
// Use `jQuery.ajax` method
$.ajax('/path/to/upload', {
method: "POST",
data: formData,
processData: false,
contentType: false,
success: function () {
console.log('Upload success');
},
error: function () {
console.log('Upload error');
}
});
});
```
### setAspectRatio(aspectRatio)
- **aspectRatio**:
- Type: `Number`
- Requires a positive number.
Change the aspect ratio of the crop box.
### setDragMode([mode])
- **mode** (optional):
- Type: `String`
- Default: `'none'`
- Options: `'none'`, `'crop'`, `'move'`
Change the drag mode.
**Tips:** You can toggle the "crop" and "move" mode by double click on the cropper.
[⬆ back to top](#table-of-contents)
## No conflict
If you have to use other cropper with the same namespace, just call the `Cropper.noConflict` static method to revert to it.
```html
```
## Browser support
- Chrome (latest 2)
- Firefox (latest 2)
- Internet Explorer 8+
- Opera (latest 2)
- Safari (latest 2)
## Contributing
Please read through our [contributing guidelines](CONTRIBUTING.md).
## Versioning
Maintained under the [Semantic Versioning guidelines](http://semver.org/).
## License
[MIT](http://opensource.org/licenses/MIT) © [Fengyuan Chen](http://chenfengyuan.com)
## Related projects
- [react-cropperjs](https://github.com/TAPP-TV/react-cropperjs) by @pbojinov
[⬆ back to top](#table-of-contents)