repository·main·Indexed 25 days ago
https://github.com/valentinh/react-easy-cropA React component for cropping images and videos with support for drag, zoom, and rotate interactions. It is mobile-friendly and provides crop dimensions in both pixels and percentages. The library includes a Cropper component with configurable props for aspect ratio, crop shape (rectangular or round), and object-fit, as well as utility functions for restoring saved crop states.
The react-easy-crop library provides the following capabilities:
react-easy-crop injects its required CSS automatically. If you choose to disable automatic injection using the disableAutomaticStylesInjection prop, you must manually import the CSS file into your project.
import 'react-easy-crop/react-easy-crop.css'
// Use with the prop to prevent double injection
<Cropper disableAutomaticStylesInjection />You can install react-easy-crop using pnpm or npm.
pnpm add react-easy-cropnpm install react-easy-crop --saveWhen restoring a previously saved crop, use the initialCroppedAreaPercentages prop instead of pixel values. Pixel values are rounded and may cause slight drift after restoration. Provide the x, y, width, and height as percentages.
<Cropper
image={image}
crop={crop}
zoom={zoom}
initialCroppedAreaPercentages={{
x: 12,
y: 8,
width: 60,
height: 45,
}}
onCropChange={setCrop}
onZoomChange={setZoom}
/>To use the cropper, wrap the Cropper component in a container element that has position: relative and a stable size (width and height). The Cropper component uses position: absolute to fill its parent container.
Key props used in the basic implementation:
image: The source image (URL or base64).crop: The current crop state (object with x and y).zoom: The current zoom level.aspect: The aspect ratio of the crop area.onCropChange: Callback function to update the crop state.onCropComplete: Callback function called when cropping is finished, providing croppedArea and croppedAreaPixels.onZoomChange: Callback function to update the zoom state.import { useState } from 'react'
import Cropper from 'react-easy-crop'
export default function Demo({ image }) {
const [crop, setCrop] = useState({ x: 0, y: 0 })
const [zoom, setZoom] = useState(1)
function onCropComplete(croppedArea, croppedAreaPixels) {
console.log(croppedArea, croppedAreaPixels)
}
return (
<div style={{ position: 'relative', width: 400, height: 300 }}>
<Cropper
image={image}
crop={crop}
zoom={zoom}
aspect={4 / 3}
onCropChange={setCrop}
onCropComplete={onCropComplete}
onZoomChange={setZoom}
/>
</div>
)
}The cropper container uses absolute positioning. To ensure the cropper displays correctly, the parent element must define the dimensions (width and height) and have position: relative.
.cropper-wrapper {
position: relative;
width: 100%;
height: 400px;
}By default, react-easy-crop automatically injects the required styles into the document head.
If you prefer to manage styles manually, set the disableAutomaticStylesInjection prop to true and import the CSS file directly from the package: react-easy-crop/react-easy-crop.css.
Cropper size appears incorrect when displayed inside a modal, ensure the modal does not use an opening animation that changes its dimensions (such as a scaling effect). Fading or sliding animations are supported and should not cause issues.When using react-easy-crop inside a modal, avoid using opening animations that change the modal's dimensions, such as scale animations. Scale animations can cause the cropper to measure the wrong size.
Fade or slide animations are safe to use and will not affect the cropper's measurements.
croppedAreaPixels property provided by the react-easy-crop component. This property contains the pixel-based coordinates and dimensions of the crop area, which can be used to draw the selection onto a <canvas> or to perform image manipulation.To create an avatar-style cropper with a circular crop area, use the Cropper component with the cropShape="round" prop. You can also disable the grid lines by setting showGrid={false} and enforce a square aspect ratio by setting ratio={1}.
<Cropper
image={image}
cropShape="round"
showGrid={false}
ratio={1}
/>The react-easy-crop cropper controls work identically for video as they do for images. To use the cropper with a video source, pass media="video" to the component (or the underlying implementation) to indicate the media type.
<CropperExample media="video" />