Registry / web-framework / react-cropper

react-cropper

library2.3.3jsnpmunverified

react-cropper provides a React component wrapper for the popular Cropper.js library, enabling declarative image cropping within React applications. As of version 2.3.3, it offers robust integration with React's component lifecycle and state management, abstracting away the direct manipulation of the Cropper.js instance. It is actively maintained with frequent patch releases, focusing on bug fixes and dependency updates, ensuring compatibility and stability. Key differentiators include its direct reliance on the well-established Cropper.js, providing a familiar API for those already accustomed to the underlying library, and its comprehensive TypeScript type definitions for improved developer experience. While it wraps Cropper.js, users still need to understand the core Cropper.js options and methods, which are exposed via a ref to the component.

web-framework

npm install react-cropper

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-CROPPER

react-cropper

web-frameworkjavascriptv2.3.3

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 'react-cropper';

✗ import { Cropper } from 'react-cropper'; const Cropper = require('react-cropper');

The primary Cropper component is a default export. For TypeScript, using 'import Cropper from "react-cropper";' is the standard.

ReactCropperElement

✓ import { ReactCropperElement } from 'react-cropper';

✗ import ReactCropperElement from 'react-cropper';

This interface is a named export, essential for correctly typing a `useRef` hook that interacts with the underlying Cropper.js instance.

cropper.css

✓ import 'cropperjs/dist/cropper.css';

✗ import 'react-cropper/dist/cropper.css'; require('cropperjs/dist/cropper.css');

The necessary stylesheet for Cropper.js is located within the `cropperjs` package itself and must be imported explicitly in your project.

Demonstrates how to import, render, and interact with the Cropper component using a `useRef` hook to access the underlying Cropper.js instance for image data and display a preview.

import React, { useRef, useState } from "react"; import Cropper, { ReactCropperElement } from "react-cropper"; import "cropperjs/dist/cropper.css"; const imageUrl = "https://raw.githubusercontent.com/roadmanfong/react-cropper/master/example/img/child.jpg"; const ImageCropperDemo: React.FC = () => { const cropperRef = useRef<ReactCropperElement>(null); const [croppedImage, setCroppedImage] = useState<string | null>(null); const onCrop = () => { const cropper = cropperRef.current?.cropper; if (cropper) { const dataUrl = cropper.getCroppedCanvas().toDataURL(); console.log('Cropped data URL:', dataUrl); setCroppedImage(dataUrl); } }; return ( <div> <h2>React Cropper Demo</h2> <Cropper src={imageUrl} style={{ height: 400, width: "100%" }} initialAspectRatio={16 / 9} guides={false} crop={onCrop} ref={cropperRef} viewMode={1} minCropBoxHeight={10} minCropBoxWidth={10} background={false} responsive={true} autoCropArea={1} checkOrientation={false} // Important for some browsers /> {croppedImage && ( <div style={{ marginTop: '20px' }}> <h3>Preview</h3> <img src={croppedImage} alt="Cropped" style={{ maxWidth: '100%', border: '1px solid #ccc' }} /> </div> )} <p>This demo shows how to integrate the Cropper component, set initial options, and retrieve the cropped image data using a ref.</p> </div> ); }; export default ImageCropperDemo;

Debug

Known issues

gotchaThe `cropperjs/dist/cropper.css` stylesheet is not bundled with `react-cropper` and must be explicitly imported in your project for the component to render correctly.

fix

Ensure you have `import 'cropperjs/dist/cropper.css';` in your entry file or a component where the Cropper is used.

affects: >=2.0.0

gotchaAccessing the underlying Cropper.js instance and its methods (e.g., `getCroppedCanvas`, `zoomTo`) requires a React `ref` to the `Cropper` component. Direct method calls on the component instance itself are not supported.

fix

Use `useRef<ReactCropperElement>(null)` in functional components and access methods via `cropperRef.current?.cropper.methodName()`.

affects: >=2.0.0

gotchaIn v2.3.2, a fix was implemented to filter out non-Cropper.js props from being passed directly to the underlying `img` element. While this is a fix, if you were relying on custom or unknown props being forwarded, their behavior might change or they might be ignored.

fix

Review props being passed to the `Cropper` component. If you need to pass specific HTML `img` attributes, ensure they are compatible or use a workaround if the prop filtering causes issues.

affects: >=2.3.2

gotchaIncorrect handling of image aspect ratio or view mode options can lead to unexpected cropping behavior, such as distorted images or non-resizable crop boxes.

fix

Carefully configure `initialAspectRatio`, `viewMode`, `minCropBoxHeight`, `minCropBoxWidth`, and `responsive` options. Refer to the Cropper.js documentation for details on each option's effect.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: cropper.getCroppedCanvas is not a function

Attempting to call a Cropper.js method before the `cropper` instance is initialized or when the ref is null/undefined.

fix

Always check if `cropperRef.current?.cropper` exists before calling any methods on it. This often happens if an event fires before the image is loaded and the cropper instance is ready.

Image appears unstyled or with incorrect UI

The required `cropperjs/dist/cropper.css` stylesheet has not been imported into the project, leading to missing styling for the cropping interface.

fix

Add `import 'cropperjs/dist/cropper.css';` to your application's entry point or the component file where `Cropper` is used.

Property 'cropper' does not exist on type 'ReactCropperElement | null'

This is a TypeScript error indicating that you are trying to access the `cropper` property on a `useRef` hook that might not yet hold an instance, or the ref is not correctly typed.

fix

Ensure your ref is typed as `useRef<ReactCropperElement>(null)` and always null-check `cropperRef.current` before accessing `cropperRef.current.cropper`.

Module not found: Can't resolve 'react-cropper' in ...

The `react-cropper` package is not correctly installed or not found by your module resolver.

fix

Run `npm install react-cropper` or `yarn add react-cropper` to install the package. Verify the package is listed in `node_modules` and your `package.json`.

Upgrade

Version history

2.3.3latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for all React components.

cropperjsrequiredProvides the core image cropping functionality and its associated CSS, which is crucial for styling. The CSS is typically imported separately.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/react-cropper/react-cropper ↗

packagehttps://www.npmjs.com/package/react-cropper ↗