React Cropper Component

Common errors

• TypeError: cropper.getCroppedCanvas is not a function

  cause 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

  cause 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'

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

  cause 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`.

Warnings

• gotcha The `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.
• gotcha Accessing 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()`.
• gotcha In 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.
• gotcha Incorrect 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.

Install

• npm install react-cropper npm
• yarn add react-cropper yarn
• pnpm add react-cropper pnpm

Imports

• Cropper
  wrong:

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

  correct:

  import Cropper from 'react-cropper';

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

  import ReactCropperElement from 'react-cropper';

  correct:

  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
  wrong:

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

  correct:

  import '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.

Quickstart

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;