{"id":10690,"library":"croppie","title":"Croppie Image Cropper","description":"Croppie is a lightweight, pure JavaScript image cropping library designed for easy integration into web applications. As of April 2026, the current stable version is 2.6.5. Its release cadence is irregular, with patches and minor feature updates released periodically, often addressing bug fixes and introducing new capabilities like blob/canvas output or improved accessibility. Key differentiators include its small footprint, lack of external dependencies (historically not requiring jQuery, although a breaking change related to jQuery events was noted in v2.6.0), keyboard navigation support (since v2.2.0), and flexible output options including base64, raw canvas, and file blobs. A significant consideration is the project's explicit statement regarding the absence of automated tests, which implies a higher risk of regressions or unexpected behavior in new releases, as acknowledged in the v2.5.0 release notes.","status":"active","version":"2.6.5","language":"javascript","source_language":"en","source_url":"https://github.com/Foliotek/Croppie","tags":["javascript","crop","cropper","image","cropping"],"install":[{"cmd":"npm install croppie","lang":"bash","label":"npm"},{"cmd":"yarn add croppie","lang":"bash","label":"yarn"},{"cmd":"pnpm add croppie","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The most common way to use Croppie in a browser, exposing the 'Croppie' constructor globally.","wrong":"import { Croppie } from 'croppie';","symbol":"Croppie","correct":"<link rel=\"stylesheet\" href=\"croppie.css\" /><script src=\"croppie.js\"></script>"},{"note":"For Node.js environments or build systems that support CommonJS module resolution. Croppie exports its constructor via `module.exports`.","wrong":"import Croppie from 'croppie';","symbol":"Croppie","correct":"const Croppie = require('croppie');"},{"note":"For type definitions when using TypeScript. The library includes its own `index.d.ts`.","symbol":"CroppieOptions","correct":"import type { CroppieOptions } from 'croppie';"}],"quickstart":{"code":"<!-- HTML: Ensure croppie.css is linked -->\n<link rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/croppie/2.6.5/croppie.min.css\">\n\n<div id=\"croppie-demo\" style=\"width: 300px; height: 300px;\"></div>\n<button id=\"get-result\">Get Cropped Image</button>\n\n<!-- JavaScript: Ensure croppie.js is loaded -->\n<script src=\"https://cdnjs.cloudflare.com/ajax/libs/croppie/2.6.5/croppie.min.js\"></script>\n<script>\n  const el = document.getElementById('croppie-demo');\n  const croppie = new Croppie(el, {\n    viewport: { width: 150, height: 150, type: 'circle' },\n    boundary: { width: 200, height: 200 },\n    showZoomer: true,\n    enableResize: true,\n    mouseWheelZoom: 'ctrl' // Only zoom when Ctrl key is pressed\n  });\n\n  croppie.bind({\n    url: 'https://images.unsplash.com/photo-1549880338-65ddcdfd017b?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTR8fGxpZ2h0aW5nfGVufDB8fDB8fHww',\n    zoom: 0\n  }).then(() => {\n    console.log('Croppie bind complete with default image.');\n  });\n\n  document.getElementById('get-result').addEventListener('click', () => {\n    croppie.result({\n      type: 'base64',\n      size: 'viewport',\n      format: 'jpeg',\n      quality: 0.8\n    }).then(function (resp) {\n      const img = new Image();\n      img.src = resp;\n      img.style.maxWidth = '100%';\n      document.body.appendChild(document.createElement('br'));\n      document.body.appendChild(document.createTextNode('Cropped Image:'));\n      document.body.appendChild(img);\n      console.log('Cropped image (base64):', resp.substring(0, 50) + '...');\n    });\n  });\n</script>\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.5.0"},{"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.","message":"By default, Croppie's mouse wheel zoom can capture scroll events, preventing normal page scrolling. This can be a disruptive user experience.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Previous versions (before 2.4.0) had known issues with `enforceBoundary: false` and correctly retrieving results, particularly in Safari and Internet Explorer 11.","severity":"gotcha","affected_versions":"<2.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Croppie script file (`croppie.js` or `croppie.min.js`) was not loaded or was not available in the current JavaScript scope.","error":"Uncaught ReferenceError: Croppie is not defined"},{"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.","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.","error":"SecurityError: The operation is insecure."},{"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.","cause":"Croppie's default behavior captures mouse wheel events for zooming, which can override page scrolling.","error":"Page scrolls unexpectedly when attempting to zoom the image with the mouse wheel within Croppie."},{"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.","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).","error":"Cropped image result is blank, corrupted, or has incorrect dimensions."}],"ecosystem":"npm"}