Croppie Image Cropper

Common errors

• Uncaught ReferenceError: Croppie is not defined

  cause The Croppie script file (`croppie.js` or `croppie.min.js`) was not loaded or was not available in the current JavaScript scope.
  fix Ensure the `<script>` tag for `croppie.js` is correctly placed in your HTML (typically before your application script) or that `require('croppie')` is used in a CommonJS environment that correctly bundles the library.

• SecurityError: The operation is insecure.

  cause Attempting to read pixel data from a canvas that contains images loaded from a different origin without proper CORS (Cross-Origin Resource Sharing) headers.
  fix Verify that all images bound to Croppie are either served from the same domain as your web application, or that the image server is configured to send `Access-Control-Allow-Origin` headers that permit cross-origin access.

• Page scrolls unexpectedly when attempting to zoom the image with the mouse wheel within Croppie.

  cause Croppie's default behavior captures mouse wheel events for zooming, which can override page scrolling.
  fix Initialize Croppie with the option `mouseWheelZoom: 'ctrl'` to require the Ctrl key to be pressed for mouse wheel zooming, allowing normal page scrolling otherwise.

• Cropped image result is blank, corrupted, or has incorrect dimensions.

  cause This can occur due to various reasons, including invalid image URLs, image loading failures, incorrect Croppie configuration (e.g., `viewport` or `boundary` too small), or issues specific to certain browsers/versions (e.g., IE11/Safari issues fixed in v2.4.0).
  fix Check the console for image loading errors. Ensure the image URL is valid and accessible. Verify `viewport` and `boundary` dimensions. If using an older version, update Croppie to at least v2.4.0 for improved browser compatibility and result reliability.

Warnings

• breaking The jQuery update event was changed or removed in v2.6.0, affecting applications that relied on Croppie's integration with jQuery's event system.
  Fix: Review and update any event handling code, especially if integrating Croppie with jQuery. Consult the documentation or changelog for specific event changes and their new implementation.
• gotcha Croppie explicitly states it lacks automated tests, increasing the risk of regressions or unexpected behavior in new releases. The v2.5.0 release notes specifically acknowledged potential breakage.
  Fix: Thoroughly test Croppie functionality within your application after any update. Consider locking to specific patch versions (e.g., `~2.6.x`) to mitigate unexpected changes from minor releases.
• gotcha By default, Croppie's mouse wheel zoom can capture scroll events, preventing normal page scrolling. This can be a disruptive user experience.
  Fix: Initialize Croppie with the option `mouseWheelZoom: 'ctrl'` to require the Ctrl key for zooming, allowing normal page scrolling when the key is not pressed. This feature was introduced in v2.6.0.
• gotcha Previous versions (before 2.4.0) had known issues with `enforceBoundary: false` and correctly retrieving results, particularly in Safari and Internet Explorer 11.
  Fix: Ensure Croppie is updated to at least v2.4.0 to resolve known rendering and result retrieval issues with `enforceBoundary: false` in affected browsers.
• gotcha Attempting to retrieve cropped image data (e.g., as canvas or blob) from an image loaded from a different origin will lead to browser security 'CORS' errors.
  Fix: Ensure all images processed by Croppie are served from the same origin as your application, or configure the image server with appropriate CORS headers (e.g., `Access-Control-Allow-Origin: *`). Alternatively, proxy images through your own backend server.

Install

• npm install croppie npm
• yarn add croppie yarn
• pnpm add croppie pnpm

Imports

• Croppie
  wrong:

  import { Croppie } from 'croppie';

  correct:

  <link rel="stylesheet" href="croppie.css" /><script src="croppie.js"></script>

  The most common way to use Croppie in a browser, exposing the 'Croppie' constructor globally.
• Croppie
  wrong:

  import Croppie from 'croppie';

  correct:

  const Croppie = require('croppie');

  For Node.js environments or build systems that support CommonJS module resolution. Croppie exports its constructor via `module.exports`.
• CroppieOptions

  import type { CroppieOptions } from 'croppie';

  For type definitions when using TypeScript. The library includes its own `index.d.ts`.

Quickstart

Initializes Croppie on an HTML element, binds a remote image URL, configures a circular viewport, enables zoom with Ctrl key, and demonstrates retrieving the cropped image as a base64 string on button click.

<!-- HTML: Ensure croppie.css is linked -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/croppie/2.6.5/croppie.min.css">

<div id="croppie-demo" style="width: 300px; height: 300px;"></div>
<button id="get-result">Get Cropped Image</button>

<!-- JavaScript: Ensure croppie.js is loaded -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/croppie/2.6.5/croppie.min.js"></script>
<script>
  const el = document.getElementById('croppie-demo');
  const croppie = new Croppie(el, {
    viewport: { width: 150, height: 150, type: 'circle' },
    boundary: { width: 200, height: 200 },
    showZoomer: true,
    enableResize: true,
    mouseWheelZoom: 'ctrl' // Only zoom when Ctrl key is pressed
  });

  croppie.bind({
    url: 'https://images.unsplash.com/photo-1549880338-65ddcdfd017b?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTR8fGxpZ2h0aW5nfGVufDB8fDB8fHww',
    zoom: 0
  }).then(() => {
    console.log('Croppie bind complete with default image.');
  });

  document.getElementById('get-result').addEventListener('click', () => {
    croppie.result({
      type: 'base64',
      size: 'viewport',
      format: 'jpeg',
      quality: 0.8
    }).then(function (resp) {
      const img = new Image();
      img.src = resp;
      img.style.maxWidth = '100%';
      document.body.appendChild(document.createElement('br'));
      document.body.appendChild(document.createTextNode('Cropped Image:'));
      document.body.appendChild(img);
      console.log('Cropped image (base64):', resp.substring(0, 50) + '...');
    });
  });
</script>