react-photo-editor

React component and hook for image editing with options to set brightness, contrast, saturation, and grayscale. Also with features to rotate, flip, pan, draw and zoom the photo.

📋 Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 📱 Live Demo
• ⚠️ Migration Guide
• 🛠️ Configuration Options
• 🧰 Advanced Usage: Custom Component with usePhotoEditor Hook
• 🤝 Contributing
• 📄 License

✨ Features

• 🎨 Color adjustments: Brightness, contrast, saturation, and grayscale
• 🔄 Image manipulation: Rotate and flip (horizontal/vertical)
• 🔍 Interactive control: Pan and zoom functionality
• ✏️ Drawing tools: Draw directly on canvas
• 🧩 Flexible integration: Use as a component or with the usePhotoEditor hook
• 🎯 Highly customizable: Configurable UI, labels, and functionality

📦 Installation

Choose your preferred package manager:

1# Using npm
2npm install react-photo-editor
3
4# Using yarn
5yarn add react-photo-editor

🚀 Quick Start

1import { useState } from 'react';
2import { ReactPhotoEditor } from 'react-photo-editor';
3
4function App() {
5  const [file, setFile] = useState();
6  const [showModal, setShowModal] = useState(false);
7
8  // Show modal if file is selected
9  const showModalHandler = () => {
10    if (file) {
11      setShowModal(true);
12    }
13  };
14
15  // Hide modal
16  const hideModal = () => {
17    setShowModal(false);
18  };
19
20  // Save edited image
21  const handleSaveImage = (editedFile) => {
22    setFile(editedFile);
23    // Do something with the edited file
24  };
25
26  const setFileData = (e) => {
27    if (e?.target?.files && e.target.files.length > 0) {
28      setFile(e.target.files[0]);
29    }
30  };
31
32  return (
33    <>
34      <input type='file' onChange={(e) => setFileData(e)} multiple={false} />
35
36      <button onClick={showModalHandler}>Edit Photo</button>
37
38      <ReactPhotoEditor
39        open={showModal}
40        onClose={hideModal}
41        file={file}
42        onSaveImage={handleSaveImage}
43      />
44    </>
45  );
46}
47
48export default App;

📱 Live Demo

See it in action on Stackblitz

⚠️ Migration Guide

Migrating from v2.x to v3.0.0

Breaking Changes

• CSS Import Removed: The CSS file import (import 'react-photo-editor/dist/style.css') is no longer required
• Tailwind CSS Configuration: No longer need to add './node_modules/react-photo-editor/dist/*.js' to your Tailwind config
• Changed canvas class name and id: The class name and id for the canvas element have been changed from canvas to rpe-canvas for better consistency with the rest of the project. Make sure to update your usage accordingly.

🛠️ Configuration Options

The ReactPhotoEditor component accepts the following props:

Prop	Type	Default	Description
file	File | undefined	Required	The input image file to be edited
allowColorEditing	boolean	true	Whether to allow color editing options
allowRotate	boolean	true	Whether to allow rotation of the image
allowFlip	boolean	true	Whether to allow flipping of the image
allowZoom	boolean	true	Whether to allow zooming of the image
allowDrawing	boolean	true	Whether to enable drawing options
downloadOnSave	boolean	false	Whether to enable downloading the edited image upon saving
open	boolean	false	Whether the photo editor modal is open
onClose	() => void	-	Function invoked when the modal is closed
onSaveImage	(image: File) => void	Required	Function invoked when the edited image is saved
modalHeight	number | string	'38rem'	Height of the photo editor modal
modalWidth	number | string	'40rem'	Width of the photo editor modal
canvasWidth	number | string	'auto'	Width of the canvas element
canvasHeight	number | string	'auto'	Height of the canvas element
maxCanvasHeight	number | string	'22rem'	Maximum height of the canvas element
maxCanvasWidth	number | string	'36rem'	Maximum width of the canvas element
labels	ReactPhotoEditorTranslations	-	Custom labels for UI elements

🧰 Advanced Usage: Custom Component with usePhotoEditor Hook

For more control over the UI and functionality, you can use the usePhotoEditor hook to build your own custom editor component.

For full examples, see the example folder.

1import { usePhotoEditor } from 'react-photo-editor';
2
3function CustomPhotoEditor({ file }) {
4  const {
5    canvasRef,
6    brightness,
7    contrast,
8    saturate,
9    grayscale,
10    setBrightness,
11    setContrast,
12    setSaturate,
13    setGrayscale,
14    handleZoomIn,
15    handleZoomOut,
16    generateEditedFile,
17    resetFilters,
18  } = usePhotoEditor({
19    file,
20    defaultBrightness: 100,
21    defaultContrast: 100,
22    defaultSaturate: 100,
23    defaultGrayscale: 0,
24  });
25
26  const handleSave = async () => {
27    const editedFile = await generateEditedFile();
28    // Do something with the edited file
29  };
30
31  return (
32    <div>
33      <canvas ref={canvasRef} />
34
35      <div>
36        <label>Brightness: {brightness}</label>
37        <input
38          type='range'
39          min='0'
40          max='200'
41          value={brightness}
42          onChange={(e) => setBrightness(Number(e.target.value))}
43        />
44      </div>
45
46      {/* Add more controls for other parameters */}
47
48      <button onClick={handleZoomIn}>Zoom In</button>
49      <button onClick={handleZoomOut}>Zoom Out</button>
50      <button onClick={resetFilters}>Reset</button>
51      <button onClick={handleSave}>Save</button>
52    </div>
53  );
54}

Hook Parameters

Parameter	Type	Default	Description
file	File | undefined	-	The image file to be edited
defaultBrightness	number	100	Initial brightness level
defaultContrast	number	100	Initial contrast level
defaultSaturate	number	100	Initial saturation level
defaultGrayscale	number	0	Initial grayscale level
defaultFlipHorizontal	boolean	false	Initial horizontal flip state
defaultFlipVertical	boolean	false	Initial vertical flip state
defaultZoom	number	1	Initial zoom level
defaultRotate	number	0	Initial rotation angle in degrees
defaultLineColor	string	#000000	Initial line color in hex code
defaultLineWidth	number	2	Initial line/stroke width
defaultMode	string	pan	Initial mode (draw or move)

Return Values

The hook returns the following values and functions:

🖼 Canvas & Image

Name	Type	Description
canvasRef	RefObject<HTMLCanvasElement>	Reference to the canvas element
imageSrc	string	The source of the loaded image

🎛 State Values & Setters

State	Setter	Type	Description
brightness	setBrightness	number	Brightness level (default 100)
contrast	setContrast	number	Contrast level (default 100)
saturate	setSaturate	number	Saturation level (default 100)
grayscale	setGrayscale	number	Grayscale level (default 0)
rotate	setRotate	number	Rotation angle in degrees
zoom	setZoom	number	Zoom level
flipHorizontal	setFlipHorizontal	boolean	Flip horizontally
flipVertical	setFlipVertical	boolean	Flip vertically
mode	setMode	'draw' | 'move'	Interaction mode (draw or move)
lineColor	setLineColor	string	Drawing line color
lineWidth	setLineWidth	number	Drawing line width

🛠 Utility Functions

Function	Type	Description
handleZoomIn	() => void	Zoom in
handleZoomOut	() => void	Zoom out
resetFilters	() => void	Reset all filters and transformations
downloadImage	() => void	Download current canvas as an image
generateEditedFile	() => Promise<File>	Returns the edited canvas as a File object

🖱 Event Handlers

Function	Type	Description
handlePointerDown	PointerEventHandler	Used for drawing
handlePointerUp	PointerEventHandler	Used for drawing
handlePointerMove	PointerEventHandler	Used for drawing
handleWheel	WheelEventHandler	Used for zooming

🤝 Contributing

Contributions to react-photo-editor are welcome! If you have any issues, feature requests, or improvements, please open an issue or submit a pull request on the GitHub repository.

How to Contribute

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add some amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a pull request

Reporting Issues

When reporting issues, please provide:

• A clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Screenshots if applicable
• Environment details (browser, OS, etc.)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.