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

File Size: 907 KB
Views Total: 66028
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
Feature Rich Image Cropping Plugin with Live Preview - Cropper.js

Cropper.js is an easy to use JavaScript/jQuery plugin for image cropping with support of live previews and custom aspect ratio.

The plugin displays a resizable grid layer on a given image allowing to visually resize and crop the image.

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.

See also:


$ 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.

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

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
  // 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

// '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
       '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

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

9. API Methods.

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

// Zoom the image.

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

// Rotate the image.

// Rotate the image to an absolute degree.

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

// Enable (unfreeze) the cropper.

// Disable (freeze) the cropper.

// Reset the cropping zone.
// Add a true param to reset the cropping zone to the default state.

// Clear the cropping zone.

// 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

// 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

// 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

// 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)

// 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

// 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

// Change the crop box position and size with new data.

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

// Get a canvas drawn the cropped image. 
// If it is not cropped, then returns a canvas drawn the whole image.
  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".

// Destroy the Cropper and remove the instance form the target image.


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


  • 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.


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


  • v0.7.8


  • fixed rounding issue when setting data


  • fixed: rotate only works half the time with uploaded images


  • fixed aspectratio calculation


  • Add "checkImageOrigin" option.


  • fixed bugs


  • fixed bugs


  • v0.7.3


  • v0.7.2


  • v0.7.1


  • v0.7.0


  • v0.6.2


  • Fix an event error


  • v0.6.0


  • v0.5.4


  • v0.5.4


  • v0.5.3


  • v0.5.2


  • v0.5.1


  • v0.5.0


  • v0.4.4


  • v0.4.3


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


  • Improve image clone


  • Rebuild to improve many details


  • Fixed a bug.


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


  • Improve issue: Crop zone exceeds natural image size


  • Fix issue: Crop zone exceeds natural image size


  • Fix issue


  • Improve.


  • Add callback for "enable" method.


  • Mobile first CSS


  • Add touch support and custom events


  • Fix a bug of"data" option


  • Fix a bug of"data" option


  • update.


  • fix a bug


  • 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.