react-photo-editor - GitLite

KO | EN

gitlite — search

#python #react #typescript #llm #golang #android #rust #deep-learning #linux #windows #vue #security #openai #open-source

react-photo-editor

(★ 83)

React component and hook for image editing, offering controls for brightness, contrast, saturation, and grayscale, along with features to rotate, flip, pan, draw, and zoom photos.

File Explorer

Download Latest Version (.zip)

- - bug_report.md
- dependabot.yml
- PULL_REQUEST_TEMPLATE..md
- - index.ts
  - interface.ts
  - ReactPhotoEditor.tsx
  - style.css
- - CustomPhotoEditor.tsx
  - PhotoEditor.tsx
- - usePhotoEditor.tsx
- - ReactPhotoEditor.test.tsx
  - usePhotoEditor.test.tsx
- App.tsx
- index.tsx
- main.tsx
- vite-env.d.ts
.eslintrc.cjs
.gitignore
.prettierignore
.prettierrc
CODE_OF_CONDUCT.md
CONTRIBUTING.md
index.html
LICENSE
package-lock.json
package.json
postcss.config.js
react-photo-editor.png
README.md
SECURITY.md
tailwind.config.js
tsconfig.json
tsconfig.node.json
vite.config.ts
vitest.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# react-photo-editor

![react-photo-editor](https://github.com/musama619/react-photo-editor/blob/main/react-photo-editor.png)

<p align="center">
  <a href="https://www.npmjs.com/package/react-photo-editor">
    <img src="https://img.shields.io/npm/v/react-photo-editor.svg" alt="NPM Version" />
  </a>
  <a href="https://www.npmjs.com/package/react-photo-editor">
    <img src="https://img.shields.io/npm/dm/react-photo-editor.svg" alt="NPM Downloads" />
  </a>
  <a href="https://bundlephobia.com/package/react-photo-editor@3.0.0">
    <img src="https://img.shields.io/bundlephobia/minzip/react-photo-editor" alt="Bundle Size" />
  </a>
  <a href="https://github.com/musama619/react-photo-editor/blob/main/LICENSE">
    <img src="https://img.shields.io/npm/l/react-photo-editor.svg" alt="License" />
  </a>
</p>

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](#-features)
- [📦 Installation](#-installation)
- [🚀 Quick Start](#-quick-start)
- [📱 Live Demo](#-live-demo)
- [⚠️ Migration Guide](#️-migration-guide)
- [🛠️ Configuration Options](#️-configuration-options)
- [🧰 Advanced Usage: Custom Component with usePhotoEditor Hook](#-advanced-usage-custom-component-with-usephotoeditor-hook)
- [🤝 Contributing](#-contributing)
- [📄 License](#-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:

```bash
# Using npm
npm install react-photo-editor

# Using yarn
yarn add react-photo-editor
```

## 🚀 Quick Start

```jsx
import { useState } from 'react';
import { ReactPhotoEditor } from 'react-photo-editor';

function App() {
  const [file, setFile] = useState();
  const [showModal, setShowModal] = useState(false);

// Show modal if file is selected
  const showModalHandler = () => {
    if (file) {
      setShowModal(true);
    }
  };

// Hide modal
  const hideModal = () => {
    setShowModal(false);
  };

// Save edited image
  const handleSaveImage = (editedFile) => {
    setFile(editedFile);
    // Do something with the edited file
  };

const setFileData = (e) => {
    if (e?.target?.files && e.target.files.length > 0) {
      setFile(e.target.files[0]);
    }
  };

return (
    <>
      <input type='file' onChange={(e) => setFileData(e)} multiple={false} />

<button onClick={showModalHandler}>Edit Photo</button>

<ReactPhotoEditor
        open={showModal}
        onClose={hideModal}
        file={file}
        onSaveImage={handleSaveImage}
      />
    </>
  );
}

export default App;
```

## 📱 Live Demo

See it in action on [Stackblitz](https://stackblitz.com/edit/react-flcdhq?file=src%2FApp.js,package.json)

## ⚠️ 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](https://github.com/musama619/react-photo-editor/blob/main/src/examples/CustomPhotoEditor.tsx) folder.

```jsx
import { usePhotoEditor } from 'react-photo-editor';

function CustomPhotoEditor({ file }) {
  const {
    canvasRef,
    brightness,
    contrast,
    saturate,
    grayscale,
    setBrightness,
    setContrast,
    setSaturate,
    setGrayscale,
    handleZoomIn,
    handleZoomOut,
    generateEditedFile,
    resetFilters,
  } = usePhotoEditor({
    file,
    defaultBrightness: 100,
    defaultContrast: 100,
    defaultSaturate: 100,
    defaultGrayscale: 0,
  });

const handleSave = async () => {
    const editedFile = await generateEditedFile();
    // Do something with the edited file
  };

return (
    <div>
      <canvas ref={canvasRef} />

<div>
        <label>Brightness: {brightness}</label>
        <input
          type='range'
          min='0'
          max='200'
          value={brightness}
          onChange={(e) => setBrightness(Number(e.target.value))}
        />
      </div>

{/* Add more controls for other parameters */}

<button onClick={handleZoomIn}>Zoom In</button>
      <button onClick={handleZoomOut}>Zoom Out</button>
      <button onClick={resetFilters}>Reset</button>
      <button onClick={handleSave}>Save</button>
    </div>
  );
}
```

### 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](https://github.com/musama619/react-photo-editor).

### 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](https://github.com/musama619/react-photo-editor/blob/main/LICENSE) file for details.