Feature-rich Image Cropper With Pure JavaScript – Cropper.js

Preview:

Description:

Cropper.js is the pure JavaScript version of the jQuery Image Cropper plugin which provides the feature-rich image cropping functionality on any image.

Main features:

• Touch-friendly.
• Powered by HTML5 canvas.
• Image rotate, zoom, flip, move.
• Cross-browser.
• Tons of options, methods, events.

Basic usage:

Install & download the Cropper.js library.

# NPM
$ npm install cropperjs --save

Import the following JavaScript and CSS files into the html file.

<link href="/path/to/cropper.min.css" rel="stylesheet">
<script src="/path/to/cropper.min.js"></script>

Wrap your image or canvas element into a container element.

<div>
  <img id="image" src="image-to-crop.jpg">
</div>

Enable the JavaScript image cropper on the image.

var image = document.getElementById('image');
var myCropper = new Cropper(image, {
    // options here
  }
});

All customization options with default values.

var image = document.getElementById('image');
var myCropper = new Cropper(image, {
    // The view mode of the cropper
    viewMode: 0, // 0, 1, 2, 3
    // The dragging mode of the cropper
    dragMode: DRAG_MODE_CROP, // 'crop', 'move' or 'none'
    // The initial aspect ratio of the crop box
    initialAspectRatio: NaN,
    // 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
    
  }
});

API methods.

var image = document.getElementById('image');
var myCropper = new Cropper(image);
// enables the crop box
myCropper.enable();
// disables the crop box
myCropper.disable();
// destroys the crop box
myCropper.destroy();
// shows the crop box
myCropper.crop();
// resets the cropper
myCropper.reset();
// clears the crop box
myCropper.clear();
// replaces the image source
myCropper.replace(url, hasSameSize);
// moves the image wrapper
myCropper.move(X, Y);
// moves to a specific point
myCropper.moveTo(X, Y);
// zooms the image
myCropper.zoom(ratio);
// zooms to
myCropper.zoomTo(ratio, pivot);
// rotates the image
myCropper.rotate(degree);
// rotates to
myCropper.rotateTo(degree);
// scales the image
myCropper.scale(scaleX, scaleY);
myCropper.scaleX(scaleX);
myCropper.scaleY(scaleY);
// gets the cropper data
myCropper.getData(rounded);
// sets the cropper data
myCropper.setData(data);
// gets container's data
myCropper.getContainerData();
// gets image data
myCropper.getImageData();
// gets canvas data
myCropper.getCanvasData();
// sets canvas data
myCropper.setCanvasData(data);
// gets data of crop box
myCropper.getCropBoxData();
// set box data;
myCropper.setCropBoxData(data);
/*
  width: the destination width of the output canvas.
  height: the destination height of the output canvas.
  minWidth: the minimum destination width of the output canvas, the default value is 0.
  minHeight: the minimum destination height of the output canvas, the default value is 0.
  maxWidth: the maximum destination width of the output canvas, the default value is Infinity.
  maxHeight: the maximum destination height of the output canvas, the default value is Infinity.
  fillColor: a color to fill any alpha values in the output canvas, the default value is transparent.
  imageSmoothingEnabled: set to change if images are smoothed (true, default) or not (false).
  imageSmoothingQuality: set the quality of image smoothing, one of "low" (default), "medium", or "high".
  rounded: set true to use rounded values (the cropped area position and size data), the default value is false.
*/
myCropper.getCroppedCanvas(options);
// sets aspect ratio
myCropper.setAspectRatio(aspectRatio);
// sets drag mode: 'none', 'crop', 'move'
myCropper.setDragMode([mode])

Event handlers.

/*  Fires when a cropper instance starts to load a image.
 *
 *  event.detail.originalEvent:
 *  Type: Event
 *  Props: mousedown, touchstart and pointerdown
 *
 *  event.detail.action:
 *  Type: String
 *  Props:
 *  'crop': create a new crop box
 *  'move': move the canvas (image wrapper)
 *  '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('cropstart', (event) => {
  console.log(event.detail.originalEvent);
  console.log(event.detail.action);
});
// Fires when the crop box is changing.
image.addEventListener('cropmove', (event) => {
  console.log(event.detail.originalEvent);
  console.log(event.detail.action);
});
// Fires when the crop box stops to change.
image.addEventListener('cropend', (event) => {
  console.log(event.detail.originalEvent);
  console.log(event.detail.action);
});
// Fires when cropping
image.addEventListener('cropend', (event) => {
  console.log(event.detail.x);
  console.log(event.detail.y);
  console.log(event.detail.width);
  console.log(event.detail.height);
  console.log(event.detail.rotate);
  console.log(event.detail.scaleX);
  console.log(event.detail.scaleY);
});
// Fires when zooming
image.addEventListener('zoom', (event) => {
  console.log(event.detail.originalEvent);
  console.log(event.detail.oldRatio);
  console.log(event.detail.ratio);
});

Changelog:

v1.6.1 (09/17/2023)

• Bugfixes

v1.6.0 (08/26/2023)

• Add a rounded option to the getCroppedCanvas method

v1.5.13 (11/20/2021)

• Add backface-visibility: hidden to the cropper image to avoid ghost lines when moving
• Remove useless cropper-hide class from cropper image.
• Check whether the parent node exists or not before removing the cropper container.

v1.5.12 (06/12/2021)

• Fix the cropper responsive when only the height was changed

v1.5.11 (02/17/2021)

• Fix TypeScript declarations compatibility

v1.5.10 (02/14/2021)

• Explicitly set the XMLHttpRequest request to be asynchronous
• Improve TypeScript declarations

v1.5.6 (10/29/2019)

• improve event type determining for iOS 13+