jQuery Plugins › jQuery Other Plugins › Cropper.js

Feature Rich Image Cropping Plugin with Live Preview - Cropper.js

File Size:	907 KB
Views Total:	66896
Last Update:	02/12/2021 07:07:00 UTC
Publish Date:	04/21/2014 10:31:05 UTC
Official Website:	Go to website
License:	MIT

Demo Download

More features:

Fully responsive and mobile-friendly.
Get/set data.
Allows to move/zoom/rotate/scale images.

Currently the jQuery Image Cropper works as a jQuery wrapper for the Cropper.js library.

Installation:

# NPM
$ npm install cropperjs --save

Basic usage:

1. Include the Cropper.js plugin's files in the web page

<link rel="stylesheet" href="/path/to/dist/cropper.min.css" />
<script src="/path/to/dist/cropper.min.js"></script>

2. Or import the Cropper.js as an ES module.

import 'cropperjs/dist/cropper.css';
import Cropper from 'cropperjs';

3. To use it as a jQuery plugin, download the jQuery Wrapper and then include the following JavaScript files on the page.

<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/dist/cropper.min.js"></script> 
<script src="/path/to/dist/jquery-cropper.min.js"></script>

4. Insert an image or canvas element into a container element.

<div>
  <img id="image" src="crop.jpg">
</div>

5. Make the image full width relative to its parent container.

img {
  max-width: 100%;
}

6. Attach the Cropper.js to the image and done.

// As a Vanilla JS plugin
const cropper = new Cropper(document.getElementById('image'), {
      // options here
});

// As a jQuery plugin
$('#image').Cropper({
  // options here
});

7. Available Options with default values.

// Define the view mode of the cropper
viewMode: 0,

// 0, 1, 2, 3
// Define the dragging mode of the cropper
dragMode: DRAG_MODE_CROP,

// 'crop', 'move' or 'none'
// Define the initial aspect ratio of the crop box
initialAspectRatio: NaN,

// Define the aspect ratio of the crop box
aspectRatio: NaN,

// An object with the previous cropping result data
data: null,

// A selector for adding extra containers to preview
preview: '',

// Re-render the cropper when resize the window
responsive: true,

// Restore the cropped area after resize the window
restore: true,

// Check if the current image is a cross-origin image
checkCrossOrigin: true,

// Check the current image's Exif Orientation information
checkOrientation: true,

// Show the black modal
modal: true,

// Show the dashed lines for guiding
guides: true,

// Show the center indicator for guiding
center: true,

// Show the white modal to highlight the crop box
highlight: true,

// Show the grid background
background: true,

// Enable to crop the image automatically when initialize
autoCrop: true,

// Define the percentage of automatic cropping area when initializes
autoCropArea: 0.8,

// Enable to move the image
movable: true,

// Enable to rotate the image
rotatable: true,

// Enable to scale the image
scalable: true,

// Enable to zoom the image
zoomable: true,

// Enable to zoom the image by dragging touch
zoomOnTouch: true,

// Enable to zoom the image by wheeling mouse
zoomOnWheel: true,

// Define zoom ratio when zoom the image by wheeling mouse
wheelZoomRatio: 0.1,

// Enable to move the crop box
cropBoxMovable: true,

// Enable to resize the crop box
cropBoxResizable: true,

// Toggle drag mode between "crop" and "move" when click twice on the cropper
toggleDragModeOnDblclick: true,

// Size limitation
minCanvasWidth: 0,
minCanvasHeight: 0,
minCropBoxWidth: 0,
minCropBoxHeight: 0,
minContainerWidth: 200,
minContainerHeight: 100,

// Shortcuts of events
ready: null,
cropstart: null,
cropmove: null,
cropend: null,
crop: null,
zoom: null

8. Events listeners.

// Vanilla JavaScript
image.addEventListener(Event, function () {});

// jQuery
image.on(Event, function () {});

image.addEventListener('ready', function () {
  // do something
});

image.addEventListener('cropstart', function (event) {
  /* event.detail.originalEvent: mousedown, touchstart and pointerdown
     event.detail.action:
       '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)
  */
});

image.addEventListener('cropmove', function (event) {
  // event.detail.originalEvent: mousemove, touchmove and pointermove
});

image.addEventListener('cropend', function (event) {
  // event.detail.originalEvent: mouseup, touchend, touchcancel, pointerup and pointercancel
});

image.addEventListener('crop', function (event) {
  /* event.detail.x
     event.detail.y
     event.detail.width
     event.detail.height
     event.detail.rotate
     event.detail.scaleX
     event.detail.scaleY
  */
});

image.addEventListener('zoom', function (event) {
  /* event.detail.originalEvent: wheel, touchmove
     event.detail.oldRatio
     event.detail.ratio
  */
});

9. API Methods.

// Show the crop box.
new Cropper(image, {
    // options here
});

// Zoom the image.
cropper.zoom(0.1);

// Zoom the canvas (image wrapper) to an absolute ratio.
cropper.zoomTo(1,{x: Number, y: Number});

// Rotate the image.
cropper.rotate(-90);

// Rotate the image to an absolute degree.
cropper.rotateTo(90);

// Scale the image.
// scale(scaleX[, scaleY])
cropper.scale(1, -1);
cropper.scaleX(1);
cropper.scaleY(1);

// Enable (unfreeze) the cropper.
cropper.enable();

// Disable (freeze) the cropper.
cropper.disable();

// Reset the cropping zone.
// Add a true param to reset the cropping zone to the default state.
cropper.reset();

// Clear the cropping zone.
cropper.clear();

// Move the canvas (image wrapper) with relative offsets.
// move(offsetX[, offsetY])
cropper.move(0, -1);

// Move the canvas (image wrapper) to an absolute point.
// moveTo(x[, y])
croppermoveTo(value1, value2);

// Replace the image.
// replace(url[, hasSameSize])
cropper.replace(example.jpg, true);

// Get the cropped zone data.
// getData([rounded])
// rounded: OPTIONAL Set true to get rounded values.
// returns:
// 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
cropper.getData([rounded]);

// Reset the cropped zone with new data.
cropper.setData({width: 480, height: 270});

// Get the container size data.
// Returns:
// width: the current width of the container
// height: the current height of the container
cropper.getContainerData();

// Get an object containing image data, contains:
// Returns:
// 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
cropper.getImageData();

// Output the canvas (image wrapper) position and size data.
// Returns:
// 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)
cropper.getCanvasData();

// Change the canvas (image wrapper) position and size with new data.
// Props:
// 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
cropper.setCanvasData(data);

// Output the crop box position and size data.
// Returns:
// 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
cropper.getCropBoxData();

// Change the crop box position and size with new data.
cropper.setCropBoxData(data);

// Enable to reset the aspect ratio after initialized.
// "auto" or a positive number ("auto" for free ratio).
cropper.setAspectRatio(1.618);

// Get a canvas drawn the cropped image. 
// If it is not cropped, then returns a canvas drawn the whole image.
cropper.getCroppedCanvas({
  width: 160,
  height: 90,
  minWidth: 256,
  minHeight: 256,
  maxWidth: 4096,
  maxHeight: 4096,
  fillColor: '#fff',
  imageSmoothingEnabled: false,
  imageSmoothingQuality: 'high',
});

// Change the drag mode.
// "crop", "move" and "none".
cropper.setDragMode("crop");

// Destroy the Cropper and remove the instance form the target image.
cropper.destroy();

Changelog:

v1.5.10 (2021-02-12)

Explicitly set the XMLHttpRequest request to be asynchronous
Improve TypeScript declarations

v1.5.9 (2020-09-11)

Fix the issue of fail to zoom out on touch device
Add TypeScript declarations for the events.

v1.5.8 (2020-09-05)

Fix the issue when the value of the minContainerWidth/Height options is 0
Reset the initial canvas size when the minCanvasWidth/Height options is set
Store the initial image data in the right place for avoiding side-effect

v1.5.7 (2020-05-23)

Improve container resizing
Improve touch device detection

2019-12-15

Updated to Cropper.js 1.5

v1.0.0 (2019-10-22)

works as a jQuery wrapper for the Cropper.js library.
Doc updated

v4.0.0 (2018-05-20)

Works as a jQuery wrapper for Cropper.js.

v3.1.5 (2018-02-25)

Fixed a bug of getCroppedCanvas method when provide maxWidth or maxHeight options

v3.1.4 (2018-01-14)

Fixed a bug of rotation

v3.1.3 (2017-10-21)

Fixed a bug of render when disable one of rotatable and scalable options.

v3.1.2 (2017-10-18)

Normalize related decimal numbers when crop an image with canvas.
Ignore unnecessary files when publish to NPM.

v3.1.1 (2017-10-12)

Supports to load in node environment.

v3.1.0 (2017-10-08)

Added 4 new options to getCroppedCanvas method: minWidth, minHeight, maxWidth and maxHeight.
Enhanced image scaling: the scaleX and scaleY values should only be 1 or -1 before, but now they can be any numbers.
Improved crop box resizing behaviour in the northeast, northwest, southeast and southwest directions.

v3.0.0 (2017-09-04)

Improve crop box resizing behaviour.

v3.0.0rc3 (2017-08-19)

Added two new options (imageSmoothingEnabled and imageSmoothingQuality) to getCroppedCanvas method.

v3.0.0rc2 (2017-05-30)

Improved performance for large images.
Fixed the issue of ArrayBuffer reference error in IE9.
Fixed an issue of canvas box initialization.

v3.0.0rc1 (2017-04-30)

Use window.jQuery instead of window.$ for browser side usage.
Change the main field value from dist/cropper.js (UMD) to dist/cropper.common.js (CommonJS).
Added module and browser fields to package.json.

v3.0.0 Beta (2017-03-25)

Clear cached pointers correctly to avoid touch zoom problem.
Improve the responsive option (only available when the container width/height great than the minContainerWidth/Height)
Improve the toggleDragModeOnDblclick option (only available when the dragMode option is set to crop or move)

v3.0.0 Beta (2017-02-25)

Fixed the bug of rotate square image lead image shrink.
Improved RegExps for DataURL processing.

v3.0.0alpha1 (2017-01-21)

Use CSS3 2D Transforms instead of left and top for better performance.
Set withCredentials attribute when read the image data by XMLHttpRequest.

v3.0.0alpha (2017-01-15)

Removed build event.
Renamed built event to ready.
Removed event namespace.
Ported code to ECMAScript 6.
Dropped IE8 support.
Improved event handler for Pointer Events (#824).
Improved setCropBoxData method.
Fixed a bug of auto crop when replace the image.

v2.3.4 (2016-09-03)

Fixed a bug of cropping in view mode 1 and 2.
Fixed a bug of calling ready event twice when call replace method.
Fixed dependencies problem in the package.json file.

v2.3.3 (2016-08-10)

Allow scroll when the dragMode is "none" on touch screens
Fixed the issue of orientation transform

v2.3.2 (2016-06-08)

Fixed wrong property reference
Fixed the wrong place of the crop event triggering
Fixed the calling order of scale and rotate

v2.3.1 (2016-05-29)

Improved the rotate and scale transform behaviour
Improved the getCroppedCanvas method to return the whole canvas if it is not cropped
Check cross origin setting when load image by XMLHTTPRequest

v2.3.0 (2016-02-22)

Added a new parameter to the replace method for applying filters.
Improved the image initializing for Safari .
Fixed incorrect size limitation of the crop box.
Fixed incorrect cropped canvas when scaleX or scaleY great than 1.

v2.2.4 (2016-01-01)

Fixed a dimension bug in the "getCroppedCanvas" method.
Added an example for cropping round image.

v2.2.3 (2015-12-28)

Supports to zoom from event triggering point.

v2.2.2 (2015-12-24)

Limit wheel speed to prevent zoom too fast
Improve the setCropBoxData method

v2.2.1 (2015-12-12)

Handle Data URL (Fixed #540: avoid to use XMLHttpRequest to open a Data URL)
Handle ajax error when load ArrayBuffer
Not to transform the image to base64 when Orientation equals to 1

v2.2.0 (2015-12-05)

Added a new option: checkOrientation
Added a timestamp to the url of preview image

v2.1.0 (2015-12-02)

Added new restore option

v2.0.2 (2015-11-30)

Fixed #476: Floor the numerical parameters for CanvasRenderingContext2D.drawImage

v2.0.1 (2015-11-18)

Supports four modes
Supports three drag modes
Improved the experience of cropping
Makes the crop box's borders and handlers visible when overflow
Fixed an issue of canvas limitation
Fixed an issue of cropping
Improved new crop box creating
Added viewMode option
Added dragMode option
Renamed touchDragZoom to zoomOnTouch
Renamed mouseWheelZoom to zoomOnWheel
Renamed doubleClickToggle to toggleDragModeOnDblclick
Renamed checkImageOrigin to checkCrossOrigin
Removed strict (supported by viewMode: 1)
Removed dragCrop (supported by dragMode: 'crop')
Added more methods and events

v1.0.0 (2015-10-10)

Improved canvas limitation
Improved preview
Improved test
Fixed an error in the clear method (missed parameters)
Fixed the issue of crop box limitaion

v1.0.0rc1 (2015-09-05)

Moved from Less to Sass
Fixed the issue of destroy method)
Fixed the issue on IE8

v0.11.1 (2015-08-22)

Optimize "built" and "crop" events
Improve the starting speed
Improve the building process
Fix event issue on IE8

v0.11.0 (2015-08-10)

Improve setCropBoxData method
Fix event issue on IE10
Optimize code (use var for per variable)

v0.10.1 (2015-07-05)

Add Pointer Events support
Add RTL support
Add one new option: "center"
Allow cropper to grow vertically

v0.10.0 (2015-06-09)

Add three new options: "change", "cropBoxMovable", "doubleClickToggle"
Change "movable" option (only for image)
Rename "resizable" to "cropBoxResizable"
Add one new event: "change.cropper"
Locking aspect ratio in "free mode" by holding shift key
Sync drag mode to crop box when it is not movable

v0.9.3 (2015-05-10)

Add new option: "data"
Add new method: "setData", "crop"
Fix incorrect minWidth/Height size of canvas
Fix the strict mode bug
Fix the crop box resizing bug

v0.9.2 (2015-04-18)

Improve strict mode to show full image
Add two new options: "minCanvasWidth" and "minCanvasHeight"
Reverse mouse wheeling zoom
Fix incorrect cursor in disabled state

v0.9.1 (2015-03-21)

Fix the touch zoom issue (#206)
Fix the reset issue

v0.9.0 (2015-03-15)

Wraps image with a virtual canvas (for zooming and rotating).
Limits image position and size in strict mode.
Supports multiple global croppers by default.
Outputs cropped canvas for display or get Data URL or get Blob
Identifies drag events with "event.dragType" property
Added zoom events for controling the canvas (image) size.
Improved responsiveness for window resizing.

2015-02-21

Refactored source code.
Compiles CSS with Less CSS preprocessors.
Supports fixed container.
Supports rotation with CSS3 Transform3d.
Add more options & methods.

2015-02-09

v0.7.8

2015-01-03

fixed rounding issue when setting data

2014-12-20

fixed: rotate only works half the time with uploaded images

2014-12-13

fixed aspectratio calculation

2014-12-06

Add "checkImageOrigin" option.

2014-11-24

fixed bugs

2014-11-20

fixed bugs

2014-11-15

v0.7.3

2014-11-11

v0.7.2

2014-11-08

v0.7.1

2014-10-21

v0.7.0

2014-10-12

v0.6.2

2014-10-04

Fix an event error

2014-09-20

v0.6.0

2014-09-05

v0.5.4

2014-08-30

v0.5.4

2014-08-23

v0.5.3

2014-08-17

v0.5.2

2014-08-13

v0.5.1

2014-08-10

v0.5.0

2014-08-05

v0.4.4

2014-08-03

v0.4.3

2014-08-01

Fixed: When `minHeight` is set, Cropper doesn't respect the aspect ratio

2014-07-30

Improve image clone

2014-07-26

Rebuild to improve many details

2014-07-12

Fixed a bug.

2014-07-12

Fixed a bug: adding $clone into DOM in function render causes a flash

2014-07-08

Improve issue: Crop zone exceeds natural image size

2014-07-06

Fix issue: Crop zone exceeds natural image size

2014-07-02

Fix issue

2014-06-11

Improve.

2014-06-02

Add callback for "enable" method.

2014-05-21

Mobile first CSS

2014-05-18

Add touch support and custom events

2014-05-15

Fix a bug of"data" option

2014-05-01

Fix a bug of"data" option

2014-04-27

update.

2014-04-24

fix a bug

2014-04-23

Add free ratio and two methods

This awesome jQuery plugin is developed by fengyuanchen. For more Advanced Usages, please check the demo page or visit the official website.

Feature Rich Image Cropping Plugin with Live Preview - Cropper.js

More features:

See also:

Installation:

Basic usage:

Changelog:

Related jQuery Plugins

You Might Also Like

Add Your Review