Easy jQuery Image Cropping Plugin with Live Previews - Image Cropper

Easy jQuery Image Cropping Plugin with Live Previews - Image Cropper
File Size: 1.92 MB
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.

See also:

Basic usage:

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

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

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

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="src/cropper.js"></script> 

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

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

4. Create container elements to display the image previews.

<div class="extra-preview extra-preview-sm"></div>
<div class="extra-preview extra-preview-xs"></div>

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

<script>
$(function() {
$(".cropper").cropper({
preview: ".extra-preview" // A jQuery selector string, add extra elements to show preview.
});
})
</script>

6. Options.

// Define the view mode of the cropper
viewMode: 0, // 0, 1, 2, 3

// Define the dragging mode of the cropper
dragMode: '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 jQuery 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 target image is cross origin
checkCrossOrigin: 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
build: null,
built: 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); // ...
});

event.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
*/
build.cropper

/*
fires when the crop box is changing.
event.dragType: The same as "dragstart.cropper".
*/
dragmove.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".
*/
dragend.cropper

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

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

8. Methods.

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

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

// Enable (unfreeze) the cropper.
$("#target").cropper("enable")

// Disable (freeze) the cropper.
$("#target").cropper("disable")

// Reset the cropping zone to the start state.
$("#target").cropper("disable")

// Reset the cropping zone.
// Add a true param to reset the cropping zone to the default state.
$("#target").cropper("reset") 

// Clear the cropping zone.
$("#target").cropper("clear")

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

// Get the cropped zone data.
$("#target").cropper("getData")

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

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

// Get the data url (base64 image) of the cropped zone.
// getDataURL([options[, type[, quality]]])
// options: A Object contains: "width", "height". Define the sizes of the result image.
// type: A String indicating the image format. The default type is image/png. Other types: "image/jpeg", "image/webp".
// quality: A Number between 0 and 1 indicating image quality if the requested type is image/jpeg or image/webp.
$("#target").cropper("getDataURL"),

// Set the cropped area data (base on the original image).
// 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
$("#target").cropper("setData", DATA),

// Destroy the Cropper and remove the instance form the target image.
$("#target").cropper("destroy")

Change logs:

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

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.