npanasenko / cropper

A simple jQuery image cropping plugin.

Image Cropper

A simple jQuery image cropping plugin.

• Demo

Features

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

Main

dist/
├── cropper.css     ( 5 KB)
├── cropper.min.css ( 4 KB)
├── cropper.js      (47 KB)
└── cropper.min.js  (18 KB)

Getting started

Quick start

Four quick start options are available:

• Download the latest release.
• Clone the repository: git clone https://github.com/fengyuanchen/cropper.git.
• Install with NPM: npm install cropper.
• Install with Bower: bower install cropper.

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.

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

$('.container > img').cropper({
  aspectRatio: 16 / 9,
  crop: 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 (wrapper), 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).

aspectRatio

• Type: Number
• Default: NaN

Set the aspect ratio of the crop box. By default, the crop box is free ratio.

crop

• Type: Function
• Default: null

This function will be executed when changes the crop box or image.

preview

• Type: String (jQuery selector)
• Default: ''

Add extra elements (containers) for previewing.

Notes:

• The maximum width is the initial width of preview container.
• The maximum height is the initial height of preview container.
• If you set an aspectRatio option, be sure to set the preview container with the same aspect ratio.

global

• Type: Boolean
• Default: true

This plugin supports multiple croppers, but only support one global cropper in the same page. If you intend to use more than one cropper, just initialize them with this option set to false.

background

• Type: Boolean
• Default: true

Show the grid background of the container.

modal

• Type: Boolean
• Default: true

Show the black modal above the crop box.

guides

• Type: Boolean
• Default: true

Show the dashed lines above the crop box.

highlight

• Type: Boolean
• Default: true

Show the withe modal above the crop box (highlight the crop box).

autoCrop

• Type: Boolean
• Default: true

Enable to crop the image automatically when initialize.

autoCropArea

• Type: Number
• Default: 0.8 (80% of the image)

A number between 0 and 1. Define the automatic cropping area size (percentage).

dragCrop

• Type: Boolean
• Default: true

Enable to remove the current crop box and create a new one by dragging over the image.

movable

• Type: Boolean
• Default: true

Enable to move the crop box.

resizable

• Type: Boolean
• Default: true

Enable to resize the crop box.

zoomable

• Type: Boolean
• Default: true

Enable to zoom the image.

mouseWheelZoom

• Type: Boolean
• Default: true

Enable to zoom the image by wheeling mouse.

touchDragZoom

• Type: Boolean
• Default: true

Enable to zoom the image by dragging touch.

rotatable

• Type: Boolean
• Default: true

Enable to rotate the image.

checkImageOrigin

• Type: Boolean
• Default: 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 and "timestamp" will be added to image url to enable "getDataURL".

Added timestamp will reload image to enable "getDataURL" on cross-origin image.

Adding "crossOrigin" attribute to image will stop adding timestamp to image url, and stop reload of image.

responsive

• Type: Boolean
• Default: true

Rebuild the cropper when resize the window.

minContainerWidth

• Type: Number
• Default: 300

The minimum width of the container.

minContainerHeight

• Type: Number
• Default: 150

The minimum height of the container.

minCropBoxWidth

• Type: Number
• Default: 0

The minimum width of the crop box.

minCropBoxHeight

• Type: Number
• Default: 0

The minimum height of the crop box.

build

• Type: Function
• Default: null

A shortcut of the "build.cropper" event.

built

• Type: Function
• Default: null

A shortcut of the "built.cropper" event.

dragstart

• Type: Function
• Default: null

A shortcut of the "dragstart.cropper" event.

dragmove

• Type: Function
• Default: null

A shortcut of the "dragmove.cropper" event.

dragend

• Type: Function
• Default: null

A shortcut of the "dragend.cropper" event.

Methods

General usage:

$().cropper('method', argument1, , argument2, ..., argumentN)

move(offsetX, offsetY)

• offsetX:
  • Type: Number
  • Moving size (px) in the horizontal direction
• offsetY:
  • Type: Number
  • Moving size (px) in the vertical direction

Move the image.

$().cropper('move', 1, 0)
$().cropper('move', 0, -1)

zoom(ratio)

• ratio:
  • Type: Number
  • Zoom in: requires a positive number (ratio > 0)
  • Zoom out: requires a negative number (ratio < 0)

Zoom the image.

$().cropper('zoom', 0.1)
$().cropper('zoom', -0.1)

rotate(degree)

• degree:
  • Type: Number
  • Rotate right: requires a positive number (degree > 0)
  • Rotate left: requires a negative number (degree < 0)

Rotate the image. Requires CSS3 Transforms3d support (IE 10+).

$().cropper('rotate', 90)
$().cropper('rotate', -90)

enable()

Enable (unfreeze) the cropper.

disable()

Disable (freeze) the cropper.

reset()

Reset the image and crop box to the initial states.

clear()

Clear the crop box.

replace(url)

• url:
  • Type: String
  • A new image url.

Replace the image and rebuild the cropper.

destroy()

Destroy the cropper and remove the instance from the image.

getData([rounded])

• rounded (optional):

  • Type: Boolean
  • Default: false
  • Rounds the output data with Math.round.

• (return):

  • Type: Object
  • 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

Get the cropped area data in the original image for cropping image.

getCropBoxData()

• (return):
  • Type: Object
  • Properties:
    • 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

Output the crop box's position and size data.

setCropBoxData(data)

• data:
  • Type: Object
  • Properties:
    • left: the new offset left of the crop box
    • top: the new offset top of the crop box
    • width: the new width of the crop box
    • height: the new height of the crop box

Change the crop box's position and size.

getImageData([all])

• all:

  • Type: Boolean
  • Default: false
  • Get all image data.

• (return):

  • Type: Object
  • Properties:
    • 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
  • More properties:
    • naturalWidth: the natural width of the image
    • naturalHeight: the natural height of the image
    • aspectRatio: the natural aspect ratio of the image
    • rotate: the rotated degrees of the image
    • rotatedLeft: the computed offset left of the rotated image
    • rotatedTop: the computed offset top of the rotated image
    • rotatedWidth: the computed width of the rotated image
    • rotatedHeight: the computed height of the rotated image

Output the image's position and size data.

setImageData(data)

• data:
  • Type: Object
  • Properties:
    • left: the new offset left of the image
    • top: the new offset top of the image
    • width: the new width of the image
    • height: the new height of the image

Change the image's position and size.

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

• options (optional):

  • Type: Object
  • properties
    • width: the destination width of the output image
    • height: the destination height of the output image
    • fillColor: a color to fill any alpha values in the output image

• type (optional):

  • Type: String
  • Default: 'image/png'
  • Options: 'image/jpeg', 'image/webp'.
  • Indicate image format.

• quality (optional):

  • Type: Number
  • Default: 1
  • Requires a number between 0 and 1
  • indicate image quality if the requested type is "image/jpeg" or "image/webp".

• (return):

  • Type: String
  • A data url of the cropped area.

• Browser support:

  • Basic image: requires Canvas support (IE 9+).
  • Rotated image: requires CSS3 Transforms3d support (IE 10+).
  • Cross-origin image: requires HTML5 CORS settings attributes support (IE 11+).

• Known issues

• Canvas: canvas.drawImage in some Mac OS / iOS browsers will rotate an image with EXIF Orientation automatically, so the output image get by canvas.toDataURL will be incorrect. To fix this, you may upload the data and crop the image in the server-side, see the example: Crop Avatar.

Get the data url (base64 image) of the cropped area by Canvas.

$().cropper('getDataURL')

$().cropper('getDataURL', {
  width: 160,
  height: 90
})

$().cropper('getDataURL', 'image/jpeg')

$().cropper('getDataURL', 'image/jpeg', 0.8)

$().cropper('getDataURL', {
  width: 320,
  height: 180
}, 'image/jpeg', 0.8)

setAspectRatio(aspectRatio)

• aspectRatio:
  • Type: Number
  • Requires a positive number.

Change the aspect ratio of the crop box.

setDragMode([mode])

• mode (optional):
  • Type: String
  • Default: ''
  • Options: 'crop', 'move'

Change the drag mode.

Tips: You can toggle the "crop" and "move" mode by double click on the cropper.

Events

build.cropper

This event fires when a cropper instance starts to load a image.

built.cropper

This event fires when a cropper instance has built completely.

dragstart.cropper

This event fires when the crop box starts to change.

Related original events: "mousedown", "touchstart".

dragmove.cropper

This event fires when the crop box is changing.

Related original events: "mousemove", "touchmove".

dragend.cropper

This event fires when the crop box stops to change.

Related original events: "mouseup", "mouseleave", "touchend", "touchleave", "touchcancel".

No conflict

If you have to use other plugin with the same namespace, just call the $.fn.cropper.noConflict method to revert to it.

<script src="other-plugin.js"></script>
<script src="cropper.js"></script>
<script>
  $.fn.cropper.noConflict();
  // Code that uses other plugin's "$().cropper" can follow here.
</script>

Browser Support

• Chrome 38+
• Firefox 33+
• Internet Explorer 8+
• Opera 25+
• Safari 5.1+

As a jQuery plugin, you can reference to the jQuery Browser Support.

License

Released under the MIT license.

Related projects

• ngCropper - AngularJS wrapper for Cropper.