cropperjs

library2.1.1jsnpmunverified

Cropper.js is a powerful, pure JavaScript library for image cropping that provides extensive functionalities including moving, zooming, rotating, and scaling images directly within web browsers. The current stable version is 2.1.1, with the project demonstrating active maintenance through consistent patch and minor releases, indicating ongoing development and bug fixes. A key differentiator is its standalone nature, operating without external dependencies like jQuery, making it lightweight and suitable for modern JavaScript ecosystems. It offers a highly configurable and extensible API, allowing developers to tailor the cropping experience precisely. The library ships with comprehensive TypeScript declaration files, ensuring excellent developer experience in TypeScript projects, and supports both UMD and ESM module formats for broad compatibility across different environments.

web-framework

npm install cropperjs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CROPPERJS

cropperjs

web-frameworkjavascriptv2.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Cropper

✓ import Cropper from 'cropperjs';

✗ const Cropper = require('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.

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); }; });

Debug

Known issues

breakingIn 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.

affects: >=2.0.0

breakingIn 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.

affects: >=2.0.0

gotchaCropper.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">`).

affects: >=1.0.0

gotchaWhen 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).

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

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

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.

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.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/fengyuanchen/cropperjs ↗

packagehttps://www.npmjs.com/package/cropperjs ↗

homepagehttps://fengyuanchen.github.io/cropperjs ↗