Easy jQuery Image Cropping Plugin with Live Previews - Image Cropper

Easy jQuery Image Cropping Plugin with Live Previews - Image Cropper
File Size: 248 KB
Views Total:
Last Update:
Publish Date:
Official Website: Go to website
License: MIT

Image Cropper is an easy to use 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.

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

See also:

Basic usage:

1. Include the jQuery image cropper plugin's stylesheet in the head section of the page.

<link rel="stylesheet" href="/path/to/cropper.css">

2. Include jQuery library and the jQuery image cropper plugin's javascript in the footer.

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

3. Insert an image you want to crop in the page.

<img class="cropper" src="picture.jpg">

4. Call the function on the image to initialize the image cropper.

  // options here

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

7. Events.

/* ('#target').on(EVENT, function (e) {

fires when a cropper instance starts to load a image.

Related original events: "mousedown", "touchstart".
$('img').on('dragstart.cropper', function (e) {
  console.log(e.type); // dragstart
  console.log(e.namespace); // cropper
  console.log(e.dragType); // ...

"crop": create a new crop box
"move": move the canvas
"zoom": zoom in / out the canvas by dragging 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

fires when the crop box is changing.
event.dragType: The same as "dragstart.cropper".

fires when the crop box stops to change.
Related original events: "mousedown", "touchstart".
event.dragType: The same as "dragstart.cropper".
Related original events: "mouseup", "mouseleave", "touchend", "touchleave", "touchcancel".

// fires when a cropper instance starts to zoom in its canvas.

// fires when a cropper instance starts to zoom out its canvas.

8. API Methods.

// Zoom the image.
$("#target").cropper("zoom", 0.1)

// Zoom the canvas (image wrapper) to an absolute ratio.
$("#target").cropper("zoomTo", 1)

// Rotate the image.
$("#target").cropper("rotate", -90)

// Rotate the image to an absolute degree.
$("#target").cropper("rotateTo", 90)

// Scale the image.
// scale(scaleX[, scaleY])
$("#target").cropper('scale', 1, -1);

// Scale the image.
$("#target").cropper('scaleX', 1);

// Scale the image.
$("#target").cropper('scaleY', 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])
$("#target").cropper('move', 0, -1);

// Move the canvas (image wrapper) to an absolute point.
// moveTo(x[, y])
$("#target").cropper('moveTo', value1, value2);

// Replace the image.
// replace(url[, onlyColorChanged])
$("#target").cropper("replace", "example.jpg")

// Get the cropped zone data.
// getData([rounded])
// rounder: OPTIONAL Set true to get rounded values.

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

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

// Get an object containing image data, contains:
// "naturalWidth", "naturalHeight", "width", "height", "aspectRatio", "ratio" and "rotate".
// The "aspectRatio" is the value of "naturalWidth / naturalHeight".
// The "ratio" is the value of "width / naturalWidth".
// The "rotate" is the rotated degree of the current image.

// Output the canvas (image wrapper) position and size data.

// Change the canvas (image wrapper) position and size with new data.
$("#target").cropper("setCanvasData", data)

// Output the crop box position and size data.

// Change the crop box position and size with new data.
$("#target").cropper("setCropBoxData", data)

// 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".
$("#target").cropper("setDragMode", "crop").

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

Change logs:

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



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