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

File Size: 907 KB
Views Total: 65209
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:

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.