{"id":11676,"library":"react-cropper","title":"React Cropper Component","description":"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.","status":"active","version":"2.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/react-cropper/react-cropper","tags":["javascript","react","react-component","cropper","image","cropperjs","typescript"],"install":[{"cmd":"npm install react-cropper","lang":"bash","label":"npm"},{"cmd":"yarn add react-cropper","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-cropper","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for all React components.","package":"react","optional":false},{"reason":"Provides the core image cropping functionality and its associated CSS, which is crucial for styling. The CSS is typically imported separately.","package":"cropperjs","optional":false}],"imports":[{"note":"The primary Cropper component is a default export. For TypeScript, using 'import Cropper from \"react-cropper\";' is the standard.","wrong":"import { Cropper } from 'react-cropper';\nconst Cropper = require('react-cropper');","symbol":"Cropper","correct":"import Cropper from 'react-cropper';"},{"note":"This interface is a named export, essential for correctly typing a `useRef` hook that interacts with the underlying Cropper.js instance.","wrong":"import ReactCropperElement from 'react-cropper';","symbol":"ReactCropperElement","correct":"import { ReactCropperElement } from 'react-cropper';"},{"note":"The necessary stylesheet for Cropper.js is located within the `cropperjs` package itself and must be imported explicitly in your project.","wrong":"import 'react-cropper/dist/cropper.css';\nrequire('cropperjs/dist/cropper.css');","symbol":"cropper.css","correct":"import 'cropperjs/dist/cropper.css';"}],"quickstart":{"code":"import React, { useRef, useState } from \"react\";\nimport Cropper, { ReactCropperElement } from \"react-cropper\";\nimport \"cropperjs/dist/cropper.css\";\n\nconst imageUrl = \"https://raw.githubusercontent.com/roadmanfong/react-cropper/master/example/img/child.jpg\";\n\nconst ImageCropperDemo: React.FC = () => {\n  const cropperRef = useRef<ReactCropperElement>(null);\n  const [croppedImage, setCroppedImage] = useState<string | null>(null);\n\n  const onCrop = () => {\n    const cropper = cropperRef.current?.cropper;\n    if (cropper) {\n      const dataUrl = cropper.getCroppedCanvas().toDataURL();\n      console.log('Cropped data URL:', dataUrl);\n      setCroppedImage(dataUrl);\n    }\n  };\n\n  return (\n    <div>\n      <h2>React Cropper Demo</h2>\n      <Cropper\n        src={imageUrl}\n        style={{ height: 400, width: \"100%\" }}\n        initialAspectRatio={16 / 9}\n        guides={false}\n        crop={onCrop}\n        ref={cropperRef}\n        viewMode={1}\n        minCropBoxHeight={10}\n        minCropBoxWidth={10}\n        background={false}\n        responsive={true}\n        autoCropArea={1}\n        checkOrientation={false} // Important for some browsers\n      />\n      {croppedImage && (\n        <div style={{ marginTop: '20px' }}>\n          <h3>Preview</h3>\n          <img src={croppedImage} alt=\"Cropped\" style={{ maxWidth: '100%', border: '1px solid #ccc' }} />\n        </div>\n      )}\n      <p>This demo shows how to integrate the Cropper component, set initial options, and retrieve the cropped image data using a ref.</p>\n    </div>\n  );\n};\n\nexport default ImageCropperDemo;","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure you have `import 'cropperjs/dist/cropper.css';` in your entry file or a component where the Cropper is used.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use `useRef<ReactCropperElement>(null)` in functional components and access methods via `cropperRef.current?.cropper.methodName()`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.3.2"},{"fix":"Carefully configure `initialAspectRatio`, `viewMode`, `minCropBoxHeight`, `minCropBoxWidth`, and `responsive` options. Refer to the Cropper.js documentation for details on each option's effect.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to call a Cropper.js method before the `cropper` instance is initialized or when the ref is null/undefined.","error":"TypeError: cropper.getCroppedCanvas is not a function"},{"fix":"Add `import 'cropperjs/dist/cropper.css';` to your application's entry point or the component file where `Cropper` is used.","cause":"The required `cropperjs/dist/cropper.css` stylesheet has not been imported into the project, leading to missing styling for the cropping interface.","error":"Image appears unstyled or with incorrect UI"},{"fix":"Ensure your ref is typed as `useRef<ReactCropperElement>(null)` and always null-check `cropperRef.current` before accessing `cropperRef.current.cropper`.","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.","error":"Property 'cropper' does not exist on type 'ReactCropperElement | null'"},{"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`.","cause":"The `react-cropper` package is not correctly installed or not found by your module resolver.","error":"Module not found: Can't resolve 'react-cropper' in ..."}],"ecosystem":"npm"}