Cropper

A simple jQuery image cropping plugin.

Download View on GitHub

Overview

Image:

Preview:

Data:

px
px
px
px

Methods:

X px
Y px
Width px
Height px
deg

Options:

Sources:

HTML:

...
<div class="img-container">
  <img src="img/picture-1.jpg">
</div>
...
<div class="img-preview"></div>
...

Javascript:

var $image = $(".img-container img"),
    $dataX = $("#dataX"),
    $dataY = $("#dataY"),
    $dataHeight = $("#dataHeight"),
    $dataWidth = $("#dataWidth");

$image.cropper({
  aspectRatio: 16 / 9,
  data: {
    x: 480,
    y: 60,
    width: 640,
    height: 360
  },
  preview: ".img-preview",
  done: function(data) {
    $dataX.val(Math.round(data.x));
    $dataY.val(Math.round(data.y));
    $dataHeight.val(Math.round(data.height));
    $dataWidth.val(Math.round(data.width));
  }
});

...

$("#reset").click(function() {
  $image.cropper("reset");
});

...

Features

Getting started

Installation

Include files:

<script src="/path/to/jquery.js"></script><!-- jQuery is required -->
<link  href="/path/to/cropper.css" rel="stylesheet">
<script src="/path/to/cropper.js"></script>

Usage

Initialize with $.fn.cropper method.

HTML:

<!-- Wrap the image with a block element -->
<div class="container">
  <img src="picture.jpg">
</div>

Javascript:

$(".container > img").cropper({
  aspectRatio: 1.618,
  done: function(data) {
    // Output the result data for cropping image.
  }
});

Notes:

- The size of the cropper inherits from the size of the image's parent element, so be sure to wrap the image with a visible block element.

- The values of the result data was computed with the original size of the image, so you can use them to crop the image directly.

Options

You may set cropper options with $().cropper(options).

If you want to change the global default options, You may use $.fn.cropper.setDefaults(options).

Name Type Default Description
aspectRatio string / number "auto" The aspect ratio of the cropping zone.
By default, the cropping zone is free ratio.
data object {} Only supports four properties: "x", "y", "width" and "height". By default, the cropping zone will appear in the center of the image.
done function function (data) {} This function will be executed when the cropping zone changes by a move, resize or crop.
preview selector "" A jquery selector, add extra elements for preview.
multiple boolean false By default, the plugin only supports one cropper per page. If you intend to use more than one, just initialize them with this option set to true.
modal boolean true Show (true) or hide (false) the black modal layer above the cropper.
dashed boolean true Show (true) or hide (false) the dashed lines above the cropping zone.
autoCrop boolean true Render the cropping zone automatically when initialize.
autoCropArea number 0.8 A number between 0 and 1. Define the automatic cropping area size (percentage).
dragCrop boolean true Enable to remove the current cropping zone and create a new one by dragging over the image.
movable boolean true Enable to move the cropping zone.
resizable boolean true Enable to resize the cropping zone.
zoomable boolean true Enable to zoom the image.
rotatable boolean true Enable to rotate the image.
checkImageOrigin boolean true By default, the plugin will check the image origin, and if it is a cross-origin image, a "crossOrigin" attribute will be added to the image element to enable "rotate" and "getDataURL".
minWidth number 0 The minimum width (px of original image) of the cropping zone.
Use this option only when you are sure that the image has this minimum width.
minHeight number 0 The minimum height (px of original image) of the cropping zone.
Use this option only when you are sure that the image has this minimum height.
maxWidth number Infinity The maximum width (px of original image) of the cropping zone.
Use this option only when you are sure that the image has this maximum width.
maxHeight number Infinity The maximum height (px of original image) of the cropping zone.
Use this option only when you are sure that the image has this maximum height.
minContainerWidth number 300 The minimum width of the cropper container.
minContainerHeight number 150 The minimum height of the cropper container.
build function null An event handler of the "build.cropper" event.
built function null An event handler of the "built.cropper" event.
dragstart function null An event handler of the "dragstart.cropper" event.
dragmove function null An event handler of the "dragmove.cropper" event.
dragend function null An event handler of the "dragend.cropper" event.

Methods

zoom

  • Zoom the image.
  • Param: a number (positive number for zoom in, negative number for zoom out).
  • Usage: $().cropper("zoom", 0.1) or $().cropper("zoom", -0.1)

rotate

  • Rotate the image (Replace the original image with a new rotated image which was generated by canvas)
  • Param: a number (positive number for rotate right, negative number for rotate left)..
  • Usage: $().cropper("rotate", 180) or $().cropper("rotate", -180)
  • Note: Be sure the browser supports canvas before call this method.

enable

  • Enable (unfreeze) the cropper
  • Usage: $().cropper("enable")

disable

  • Disable (freeze) the cropper
  • Usage: $().cropper("disable")

reset

  • Reset the cropping zone to the start state.
  • Add a true param to reset the cropping zone to the default state.
  • Usage: $().cropper("reset") or $().cropper("reset", true)

clear

  • Clear the cropping zone.
  • Usage: $().cropper("clear").

replace

  • Replace the image.
  • Usage: $().cropper("replace", "example.jpg").

destroy

  • Destroy the cropper and remove the instance from the image.
  • Usage: $().cropper("destroy").

getData

  • Get the cropped zone data. Add a true parameter to get rounded data.
  • Usage: $().cropper("getData") or $().cropper("getData", true).

setData

  • Reset the cropped zone with new data.
  • Param: an object containing "x1", "y1", "width", "height".
  • Usage: $().cropper("setData", {width: 480, height: 270}).
  • Tip: If you want to remove the current data, just pass an empty object or null. For example: $().cropper("setData", {}) or $().cropper("setData", null).

setAspectRatio

  • Enable to reset the aspect ratio after built.
  • Param: "auto" or a positive number ("auto" for free ratio).
  • Usage: $().cropper("setAspectRatio", 1.618).

getImageData

  • 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.
  • Usage: $().cropper("getImageData").

setDragMode

  • Change the drag mode.
  • Params: "crop", "move" and "none".
  • Usage: $().cropper("setDragMode", "crop").
  • Tips: You can toggle the "crop" and "move" mode by double click on the image.

getDataURL([options[, type[, quality]]])

  • Get the data url (base64 image) of the cropped zone.
  • Param @options: A Object contains: "width", "height". Define the sizes of the result image.
  • Param @type: A String indicating the image format. The default type is image/png. Other types: "image/jpeg", "image/webp".
  • Param @quality: A Number between 0 and 1 indicating image quality if the requested type is image/jpeg or image/webp.
  • Usage: $().cropper("getDataURL") or $().cropper("getDataURL", {width:100, height: 100}, "image/jpeg", 0.6) or $().cropper("getDataURL", "image/jpeg") or $().cropper("getDataURL", "image/jpeg", 0.6).
  • Note: Be sure the browser supports canvas before call this method.

Events

build.cropper

This event will be fired when the Cropper starts to build.

built.cropper

This event will be fired when the Cropper has been built.

dragstart.cropper

This event will be fired before the cropping zone start to move.

dragmove.cropper

This event will be fired when the cropping zone was moving.

dragend.cropper

This event will be fired after the cropping zone stop to move.

Examples

Cropper with fixed dragger.

Demo:

Picture

HTML:

<div class="fixed-dragger-cropper">
  <img src="img/picture-1.jpg">
</div>

JavaScript:

$(".fixed-dragger-cropper > img").cropper({
  aspectRatio: 640 / 320,
  autoCropArea: 0.6, // Center 60%
  multiple: false,
  dragCrop: false,
  dashed: false,
  movable: false,
  resizable: false,
  built: function () {
    $(this).cropper("zoom", 0.5);
  }
});

Cropper in a Bootstrap modal

HTML:

<div class="modal" id="bootstrap-modal">
  <div class="modal-dialog">
    ...
    <div class="modal-body">
      <div class="bootstrap-modal-cropper">
        <img src="img/picture-1.jpg">
      </div>
    </div>
    ...
  </div>
</div>

Demo:

JavaScript:

var $image = $(".bootstrap-modal-cropper > img"),
    originalData = {};

$("#bootstrap-modal").on("shown.bs.modal", function() {
  $image.cropper({
    multiple: true,
    data: originalData,
    done: function(data) {
      console.log(data);
    }
  });
}).on("hidden.bs.modal", function() {
  originalData = $image.cropper("getData");
  $image.cropper("destroy");
});

Crop avatar A complete example

This example require a PHP server, please download and test it.

Download View the sources