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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ReactCrop
✓ import ReactCrop from 'react-image-crop'
✗ const ReactCrop = require('react-image-crop')
Primarily designed for ESM environments. While CommonJS may work via transpilation, direct `require` is not the idiomatic way for modern React development.
Crop (type)
✓ import { type Crop } from 'react-image-crop'
✗ import { Crop } from 'react-image-crop'
Importing types requires the `type` keyword for cleaner separation and better tree-shaking in modern TypeScript/ESM setups. Other types like `PixelCrop` and `PercentCrop` are also available.
CSS Stylesheet
✓ import 'react-image-crop/dist/ReactCrop.css'
✗ import 'react-image-crop/ReactCrop.css'
The CSS file is located in the 'dist' directory. Ensure your bundler is configured to handle CSS imports. Note potential issues and breaking changes with the CSS filename in specific v11 releases, particularly concerning Vite 6 (see warnings).
Demonstrates basic image cropping functionality, allowing users to define a crop area on a placeholder image and observing the crop state in real-time.
import React, { useState } from 'react'
import ReactCrop, { type Crop } from 'react-image-crop'
import 'react-image-crop/dist/ReactCrop.css'
function CropDemo({ src = 'https://picsum.photos/800/600' }) {
const [crop, setCrop] = useState<Crop>()
// In a real application, 'src' would typically come from user input or an API.
// This example uses a static placeholder image for simplicity.
return (
<div style={{ maxWidth: '600px', margin: 'auto', border: '1px solid #eee', padding: '10px' }}>
<h2>React Image Crop Demo</h2>
<p>Drag the handles on the image below to define a crop area.</p>
<ReactCrop crop={crop} onChange={c => setCrop(c)} aspect={16 / 9}>
<img src={src} alt="Source to crop" style={{ maxWidth: '100%', height: 'auto', display: 'block' }} />
</ReactCrop>
<p>Current crop state:</p>
<pre style={{ background: '#f8f8f8', padding: '10px', borderRadius: '4px' }}>
{JSON.stringify(crop, null, 2)}
</pre>
<p><em>(Click on the image and drag to create or adjust a crop selection)</em></p>
</div>
)
}
export default CropDemo;
Debug
Known issues
breakingVersion 11.0.8 (and potentially other releases between 11.0.8 and 11.0.10) introduced an accidental breaking change by altering the CSS filename from `ReactCrop.css`. While `11.0.10` addresses this and stabilizes the path, users on affected versions might encounter 'Module not found' errors for the CSS.fixUpgrade to `react-image-crop@11.0.10` or newer. Always use the import path `import 'react-image-crop/dist/ReactCrop.css'`. For Vite 6 users experiencing issues, ensure your bundler configuration is aligned with the package's expectations.
affects: >=11.0.8 <11.0.10
gotchaThe `onChange` prop is a controlled component mechanism and is mandatory. You must implement this callback to update your component's `crop` state, otherwise, the cropping tool will appear unresponsive and unusable.fixEnsure that the `onChange` prop receives a function that updates the `crop` state using a `useState` hook or similar state management, e.g., `<ReactCrop crop={crop} onChange={c => setCrop(c)} />`. affects: >=11.0.0
gotchaWhen manually setting the `crop` prop, it is crucial to ensure the crop dimensions are within the image bounds and adhere to any specified aspect ratio. Incorrect or invalid `crop` values can lead to unexpected UI behavior, an invisible crop area, or JavaScript errors.fixUtilize helper functions like `makeAspectCrop` and `centerCrop` provided by the library to correctly calculate and position the crop. Always validate incoming `crop` values before updating your state.
affects: >=11.0.0
gotchaAs of version 11.0.0, the `ReactCrop` component no longer applies `overflow: hidden` to its primary container. This design change provides more flexibility for customization but means elements like crop handles can visually extend beyond the component's boundaries during interaction.fixIf `overflow: hidden` is desired for the component's visible area, apply it manually to a wrapper `div` around `ReactCrop` in your application's CSS.
affects: >=11.0.0
gotchaReact Image Crop explicitly states it does not support Internet Explorer. It targets modern web browsers for full functionality and performance.fixEnsure your project's browser compatibility requirements exclude Internet Explorer, or consider providing an alternative solution or polyfills if legacy browser support is a necessity for your application.
affects: All versions
Errors
Common errors & fixes
Module not found: Error: Can't resolve 'react-image-crop/dist/ReactCrop.css' in '...'
The CSS stylesheet for React Image Crop could not be located at the specified import path. This is commonly due to an incorrect path, issues with bundler configuration (e.g., Webpack, Vite), or the aforementioned CSS filename change in specific v11 releases.
fixVerify the import statement is `import 'react-image-crop/dist/ReactCrop.css'`. Ensure your bundler is correctly configured to process CSS imports. If using Vite 6, and you're on an older version of react-image-crop, consider upgrading to 11.0.10+ as it includes fixes for Vite compatibility.
TypeError: Cannot read properties of undefined (reading 'width') or similar errors related to crop properties on mount/load.
This typically occurs when the `crop` prop passed to `ReactCrop` is `undefined` or an incomplete object, especially during initial component rendering or when an image is loaded without a properly initialized crop state.
fixInitialize your `crop` state with a valid `Crop` object or `undefined` (if no initial crop is desired). Ensure that when an image is loaded or resized, your state management properly sets or clears the `crop` object before it's used by `ReactCrop`. Use `useState<Crop | undefined>()` and defensively handle potentially undefined `crop` values.
Audit
Dependencies
reactrequiredPeer dependency required for all React components.