Cropper.js - JavaScript Image Cropper

Common errors

• Uncaught TypeError: Cannot read properties of undefined (reading 'appendChild')

  cause Cropper.js CSS file is not loaded, leading to rendering issues or JavaScript errors when the library tries to manipulate non-existent or incorrectly styled elements.
  fix Add `import 'cropperjs/dist/cropper.css';` to your main JavaScript/TypeScript file or ensure the CSS is included in your HTML.

• Uncaught DOMException: Failed to execute 'toDataURL' on 'HTMLCanvasElement': Tainted canvases may not be exported.

  cause Attempting to export a canvas as an image (e.g., `toDataURL`, `toBlob`) when the image source is from a different origin and CORS headers are not correctly configured.
  fix Add the `crossorigin="anonymous"` attribute to your `<img>` tag. Verify the image server is configured to send `Access-Control-Allow-Origin` headers that permit requests from your domain.

• Cropper is not a constructor

  cause Using `require('cropperjs')` directly in a CommonJS environment without accessing the default export.
  fix For CommonJS, use `const Cropper = require('cropperjs').default;`. For modern JavaScript modules, stick to `import Cropper from 'cropperjs';` and ensure your bundler (e.g., Webpack, Rollup) or TypeScript configuration (`esModuleInterop: true`) handles default interop correctly.

• Image glitches or crop box appears unstable during drag/resize.

  cause This can stem from conflicting global CSS styles (e.g., `box-sizing`), or complex DOM structures like Shadow DOM where event target calculation can be tricky.
  fix Inspect your CSS for conflicting rules, particularly `box-sizing` on elements within or around the cropper. Ensure no other scripts are interfering with mouse events. Check if upgrading to a newer Cropper.js version (e.g., v2.1.0 addressed shadow DOM event target issues) resolves the problem.

Warnings

• breaking In v2.0.0-rc, the default values for `rotatable`, `scalable`, `skewable`, and `translatable` properties on `CropperImage` were changed from `true` to `false`. Features that previously worked out-of-the-box now require explicit enabling through options.
  Fix: Explicitly set `rotatable: true`, `scalable: true`, `skewable: true`, or `translatable: true` in the Cropper options if these features are desired.
• breaking In v2.0.0-rc.0, the `linked` property of `CropperSelection` was renamed to `dynamic`. Any code referencing the `linked` property will break.
  Fix: Update your code to use the `dynamic` property instead of `linked` for CropperSelection configurations.
• gotcha Cropper.js relies heavily on its default CSS for correct rendering and functionality. If the UI appears broken or non-functional, it's often due to missing or improperly loaded styles.
  Fix: Ensure that `cropperjs/dist/cropper.css` is correctly imported in your JavaScript entry point (`import 'cropperjs/dist/cropper.css';`) or linked in your HTML (`<link rel="stylesheet" href="node_modules/cropperjs/dist/cropper.css">`).
• gotcha When loading images from a different origin (domain, protocol, or port), using `getCroppedCanvas()` will result in a 'Tainted canvases may not be exported' error due to browser security restrictions (CORS).
  Fix: Set the `crossorigin="anonymous"` attribute on your `<img>` tag. Additionally, ensure the server hosting the image is configured with appropriate CORS headers (e.g., `Access-Control-Allow-Origin: *` or your specific origin).

Install

• npm install cropperjs npm
• yarn add cropperjs yarn
• pnpm add cropperjs pnpm

Imports

• Cropper
  wrong:

  const Cropper = require('cropperjs');

  correct:

  import Cropper from 'cropperjs';

  Cropper.js v2+ primarily exports a default. For CommonJS, `require('cropperjs').default` is typically needed.
• CropperOptions

  import type { CropperOptions } from 'cropperjs';

  For type-only imports in TypeScript, use the `type` keyword. This helps avoid bundling unnecessary code.
• CSS

  import 'cropperjs/dist/cropper.css';

  The core CSS is essential for Cropper.js to render and function correctly. It must be imported or linked.

Quickstart

This quickstart demonstrates how to initialize Cropper.js with an image element, including essential CSS and basic configuration options like aspect ratio and view mode, and logs crop events.

import Cropper from 'cropperjs';
import 'cropperjs/dist/cropper.css';

document.addEventListener('DOMContentLoaded', () => {
  const container = document.createElement('div');
  container.style.width = '800px';
  container.style.height = '600px';
  container.style.margin = '20px auto';
  container.style.border = '1px solid #ccc';
  container.style.display = 'flex';
  container.style.justifyContent = 'center';
  container.style.alignItems = 'center';
  document.body.appendChild(container);

  const image = document.createElement('img');
  image.id = 'image-to-crop';
  image.src = 'https://picsum.photos/800/600'; // Example image source
  image.alt = 'Image for cropping';
  image.style.maxWidth = '100%';
  image.style.maxHeight = '100%';
  container.appendChild(image);

  // Wait for the image to load before initializing Cropper
  image.onload = () => {
    const cropper = new Cropper(image, {
      aspectRatio: 16 / 9,
      viewMode: 1, // 0: no restrictions, 1: restrict to container, 2: restrict to canvas, 3: restrict to image
      background: false, // Hide the grid background
      crop(event) {
        console.log('Crop data:', event.detail);
      },
      ready() {
        console.log('Cropper is ready!');
      }
    });

    // Example: Destroy cropper after 10 seconds
    // setTimeout(() => {
    //   cropper.destroy();
    //   console.log('Cropper destroyed.');
    // }, 10000);
  };
});