# Cropper

A simple jQuery image cropping plugin.

Download View on GitHub

# Overview

### Image:

### Preview:

### Data:

X px
Y px
Width px
Height px

### Methods:

X px
Y px
Width px
Height px
deg

### Options:

autoCrop:
Yes No
dragCrop:
Yes No
modal:
Yes No
dashed:
Yes No
movable:
Yes No
resizable:
Yes No
zoomable:
Yes No
rotatable:
Yes No
multiple:
Yes No

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

- Supports touch
- Supports zoom
- Supports rotation
- Supports canvas
- Supports options
- Supports methods
- Supports events
- Cross-browser support

# 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:

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:

#### Cropper

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