Lightweight & Fast Image Cropper In Vanilla JavaScript – Truecropper.js

TrueCropperis a lightweight, customizable, dependency-free JavaScript image cropper for both web & mobile.

It works precisely with real image pixel sizes and supports touch devices. The cropped image data is stored within the image’s dataset, ready for you to use.

You can customize the cropping experience by adjusting various settings, such as aspect ratio, minimum/maximum size, and more.

How to use it:

1. Install & download Truecropper via NPM.

# NPM
$ npm install truecropper

2. Import the Truecropper component into your project.

// ES module
import TrueCropper from "truecropper";
// OR
import TrueCropper from "./dist/trueCropper.es.js";

3. Initialize TrueCropper on your image that needs cropping.

<div class="truecropper">
  <img src="/path/to/image-to-crop.jpg" id="example" />
</div>

const myCropper = new TrueCropper("#example", {
      // options here
});

4. Available options to customize the image cropper. Note that all options listed below can be passed via HTML data attributes:

const myCropper = new TrueCropper("#example", {
      // data-truecropper-aspect-ratio
      aspectRatio: 1,
      // data-truecropper-allow-flip
      allowFlip: true,
      // data-truecropper-allow-new-selection
      allowNewSelection: true,
      // data-truecropper-allow-move
      allowMove: true,
      // data-truecropper-allow-resize
      allowResize: true,
      // how the crop region should be calculated
      // "real", "percent" or "relative"
      // data-truecropper-return-mode
      returnMode: "real",
      minSize: {
        // data-truecropper-min-size-width
        width: null, 
        // data-truecropper-min-size-height
        height: null, 
        // // 'real' or 'percent' or 'relative', 
        // data-truecropper-min-size-unit
        unit: null, 
      },
      maxSize: {
        // data-truecropper-max-size-width
        width: null, 
        // data-truecropper-max-size-height
        height: null, 
        // 'real' or 'percent' or 'relative', 
        // data-truecropper-max-size-unit
        unit: null,
      },
      startSize: {
        // data-truecropper-start-size-x
        x: 0,
        // data-truecropper-start-size-y
        y: 0,
        // data-truecropper-start-size-width
        width: 100, 
        // data-truecropper-start-size-height
        height: 100, 
        // 'real' or 'percent' or 'relative', 
        // data-truecropper-start-size-unit
        unit:'percent',
      },
      defaultSize: {
        // data-truecropper-default-size-x
        x: 0,
        // data-truecropper-default-size-y
        y: 0,
        // data-truecropper-default-size-width
        width: 100, 
        // data-truecropper-default-size-height
        height: 100, 
        // 'real' or 'percent' or 'relative', 
        // data-truecropper-default-size-unit
        unit:'percent',
      },
});

5. Callback functions.

const myCropper = new TrueCropper("#example", {
      onInitialize: function(instance, data) {
        // data = {x, y, width, height}
      }
      onCropStart: function(instance, data) {
        // data = {x, y, width, height}
      }
      onCropMove: function(instance, data) {
        // data = {x, y, width, height}
      }
      onCropEnd: function(instance, data) {
        // data = {x, y, width, height}
      }
      onError: function(instance, data) {
        // data = CallbackError
      }
});

6. API methods.

// Returns the round value of the crop region.
myCropper.getValue();
myCropper.getValue(returnMode);
// Returns the image props: 
// { real: { width, height }, relative: { width, height } }
myCropper.getImageProps();
// Gets the status of the instance
myCropper.getStatus();
// Sets the crop region by properties.
myCropper.setValue({ 
  x: number, 
  y: number, 
  width: number, 
  height: number 
});
// Moves the crop region
myCropper.moveTo({
  x: number, 
  y: number 
});
// Resizes the crop region
myCropper.resizeTo({
   width: number, 
   height: number 
}, origin);
// Scales the crop region by a factor
myCropper.scaleBy(factor: number, origin?: Array);
// Changes image path
myCropper.setImage(src: string);
// Resets the cropper
myCropper.reset();
// Destroys the instance
myCropper.destroy();

Changelog:

v1.0.3 (06/05/2025)

• update getImagePreview method. Add img.complite condition to check image is alredy load