gem-hunter

A React component to crop images/videos with easy interactions

Check out the hosted examples:

• Basic example
• Example with output of the cropped image
• Example with image selected by the user
• Example with round crop area and no grid
• Example with a video
• Example with crop saved/loaded

• Supports drag, zoom and rotate interactions
• Provides crop dimensions as pixels and percentages
• Supports any images format (JPEG, PNG, even GIF) as url or base 64 string
• Supports any videos format supported in HTML5
• Mobile friendly

If react-easy-crop doesn't cover your needs we recommend taking a look at Pintura

Pintura features cropping, rotating, flipping, filtering, annotating, and lots of additional functionality to cover all your image and video editing needs on both mobile and desktop devices.

Learn more about Pintura

• Create an image gallery with live cropping By Coding With Adam
• Crop an avatar and download the result By Manish Boro

pnpm add react-easy-crop

or

npm install react-easy-crop --save

The Cropper is styled with position: absolute to take the full space of its parent. Thus, you need to wrap it with an element that uses position: relative or the Cropper will fill the whole page.

import { useState, useCallback } from 'react'
import Cropper from 'react-easy-crop'

const Demo = () => {
  const [crop, setCrop] = useState({ x: 0, y: 0 })
  const [zoom, setZoom] = useState(1)

  const onCropComplete = (croppedArea, croppedAreaPixels) => {
    console.log(croppedArea, croppedAreaPixels)
  }

  return (
    <Cropper
      image={yourImage}
      crop={crop}
      zoom={zoom}
      aspect={4 / 3}
      onCropChange={setCrop}
      onCropComplete={onCropComplete}
      onZoomChange={setZoom}
    />
  )
}

This component requires some styles to be available in the document. By default, you don't need to do anything, the component will automatically inject the required styles in the document head. If you want to disable this behaviour and manually inject the CSS, you can set the disableAutomaticStylesInjection prop to true and use the file available in the package: react-easy-crop/react-easy-crop.css.

If you are using the Cropper inside a modal, you should ensure that there is no opening animation that is changing the modal dimensions (scaling effect). Fading or sliding animations are fine. See #428, #409, #267 or #400 for more details.

This callback is the one you should use to save the cropped area of the media. It's passed 2 arguments:

1. croppedArea: coordinates and dimensions of the cropped area in percentage of the media dimension
2. croppedAreaPixels: coordinates and dimensions of the cropped area in pixels.

Both arguments have the following shape:

const area = {
  x: number, // x/y are the coordinates of the top/left corner of the cropped area
  y: number,
  width: number, // width of the cropped area
  height: number, // height of the cropped area
}

This is the exact same callback as onCropComplete, but is triggered for all user interactions. It can be used if you are not performing any render action on it.

1. croppedArea: coordinates and dimensions of the cropped area in percentage of the media dimension
2. croppedAreaPixels: coordinates and dimensions of the cropped area in pixels.

Both arguments have the following shape:

const area = {
  x: number, // x/y are the coordinates of the top/left corner of the cropped area
  y: number,
  width: number, // width of the cropped area
  height: number, // height of the cropped area
}

Called when media gets successfully loaded. This is useful if you want to have a custom zoom/crop strategy based on media size.

Example:

const CONTAINER_HEIGHT = 300

const CroppedImage = ({ image }) => {
  const [crop, onCropChange] = React.useState({ x: 0, y: 0 })
  const [zoom, onZoomChange] = React.useState(1)
  return (
    <Cropper
      image={image}
      crop={crop}
      zoom={zoom}
      onCropChange={onCropChange}
      onZoomChange={onZoomChange}
      onMediaLoaded={(mediaSize) => {
        // Adapt zoom based on media size to fit max height
        onZoomChange(CONTAINER_HEIGHT / mediaSize.naturalHeight)
      }}
    />
  )
}

[Advanced Usage]

Used to calculate values for crop and zoom based on a desired croppedAreaPercentages value.

[Advanced Usage]

See getInitialCropFromCroppedAreaPercentages.

pnpm install
pnpm start

Now, open http://localhost:3001/index.html and start hacking!

MIT

This project is maintained by Valentin Hervieu.

This project was originally part of @ricardo-ch organisation because I (Valentin) was working at Ricardo. After leaving this company, they gracefully accepted to transfer the project to me. ❤️

Thanks goes to these wonderful people (emoji key):

Valentin Hervieu 💬 🐛 💻 📖 💡 🚇 👀 ⚠️ 🔧	Juntae Kim 💻	tafelito 💻	Nicklas 💻	Kyle Poole 💻	Nathaniel Bibler 💻	TheRealSlapshot 💻
Claudiu Andrei 💻	MattyBalaam 💻	Christian Kehr 📖	Christopher Albanese 💻	Benjamin Piouffle 💻	mbalaam 📖	Edouard Short 💻 🤔
All Contributors 🔧	FillPower1 💻	Nihey Takizawa 📖	Alex Lende 🚧	Stefano Ruth 💻 🤔	David Vail 💻	ersefuril 💻
Michal-Sh 💻	Ivan Galiatin 💻 💡	Raed 🚇 📖	cvolant 💻	CodingWith-Adam 📖	LiveBoom 💻	Mateusz Juszczyk 💻
Darren Labithiotis 💻	Oleksii 📖	Vass Bence 📖 💻	Anthony Utt 📖 💻	Sean Parmelee 📖 💻	Glen Davies 💻	carlosdi0 📖
Hüseyin Büyükdere 📖	Pontus Magnusson 💻	kruchkou 💻	Rik 📖	Abdullah Alaqeel 💻	Thomas Johansen 💻	José Guardiola 💻 📖
IanSymplectic 💻	Logan Price 💻	allcontributors[bot] 📖	Martin Clavin 💻	Osny Netto 📖 💻	Brad Jorsch 🚇	Hyeryong Choi 💻

This project follows the all-contributors specification. Contributions of any kind welcome!