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

Preview:

Description:

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

Main features:

• Touch-friendly.
• Powered by HTML5 canvas.
• Image rotate, zoom, flip, move.
• Extensible and Customizable.
• CSS-in-JS.
• Import on-demand
• Tons of options, methods, and events.

Basic usage (v2):

1. Install & download the Cropper.js library.

# NPM
$ npm install cropperjs --save

2. Import Cropper.js into your project.

import Cropper from 'cropperjs';

// OR
<script src="https://unpkg.com/cropperjs"></script>

3. Wrap your image or canvas element into a container element.

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

4. Enable the JavaScript image cropper on the image.

const cropper = new Cropper('#image');

5. Or import all Cropper elements from the cropperjs package and define them as custom elements automatically.

import 'cropperjs';

<cropper-canvas background>
  <cropper-image src="/path/to/image.jpg" alt="Picture" rotatable scalable skewable translatable></cropper-image>
  <cropper-shade hidden></cropper-shade>
  <cropper-handle action="select" plain></cropper-handle>
  <cropper-selection initial-coverage="0.5" movable resizable>
    <cropper-grid role="grid" covered></cropper-grid>
    <cropper-crosshair centered></cropper-crosshair>
    <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle>
    <cropper-handle action="n-resize"></cropper-handle>
    <cropper-handle action="e-resize"></cropper-handle>
    <cropper-handle action="s-resize"></cropper-handle>
    <cropper-handle action="w-resize"></cropper-handle>
    <cropper-handle action="ne-resize"></cropper-handle>
    <cropper-handle action="nw-resize"></cropper-handle>
    <cropper-handle action="se-resize"></cropper-handle>
    <cropper-handle action="sw-resize"></cropper-handle>
  </cropper-selection>
</cropper-canvas>

6. Available options for the Cropper().

const cropper = new Cropper('#image',{
   container: null,
   template: '
      <cropper-canvas background>
      <cropper-image></cropper-image>
      <cropper-shade hidden></cropper-shade>
      <cropper-handle action="select" plain></cropper-handle>
      <cropper-selection initial-coverage="0.5" movable resizable>
        <cropper-grid role="grid" bordered covered></cropper-grid>
        <cropper-crosshair centered></cropper-crosshair>
        <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle>
        <cropper-handle action="n-resize"></cropper-handle>
        <cropper-handle action="e-resize"></cropper-handle>
        <cropper-handle action="s-resize"></cropper-handle>
        <cropper-handle action="w-resize"></cropper-handle>
        <cropper-handle action="ne-resize"></cropper-handle>
        <cropper-handle action="nw-resize"></cropper-handle>
        <cropper-handle action="se-resize"></cropper-handle>
        <cropper-handle action="sw-resize"></cropper-handle>
      </cropper-selection>
    </cropper-canvas>'
});

7. API methods.

// Get the <cropper-canvas> element in the Cropper container.
cropper.getCropperCanvas()
// Get the <cropper-image> element in the Cropper container.
cropper.getCropperImage();
// Get the <cropper-selection> element in the Cropper container.
cropper.getCropperSelection();
// Get all the <cropper-selection> elements in the Cropper container when there are multiple selections.
cropper.getCropperSelections()

8. Check out the official website for full DOCs.

Changelog:

v2.0.0 (03/01/2025)

• Refactor and bugfix

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+