https://github.com/thegreatercurve/react-simple-crop
✂️ A React component library for cropping and previewing images
https://github.com/thegreatercurve/react-simple-crop
crop crop-image cropper image-crop javascript react
Last synced: 3 months ago
JSON representation
✂️ A React component library for cropping and previewing images
- Host: GitHub
- URL: https://github.com/thegreatercurve/react-simple-crop
- Owner: thegreatercurve
- License: mit
- Created: 2019-06-09T17:07:37.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T07:36:48.000Z (over 2 years ago)
- Last Synced: 2025-06-25T00:12:32.915Z (3 months ago)
- Topics: crop, crop-image, cropper, image-crop, javascript, react
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-simple-crop
- Size: 2.68 MB
- Stars: 21
- Watchers: 1
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React Simple Crop
A simple, easy-to-use and dependecy-free library for cropping images in React.
## Features
- Responsive and touch enabled
- Crop supports mimimum and maximum sizes
- Crop can conform to an aspect ratio
- Crop can be refined with arrow keys
- Dependency-free (only 8kb minified)
- Compatible with >IE11
- Typescript support
- Accessible
## Installation
```
npm i react-simple-crop
```
## Demo
A simple example can be found [here on CodeSandbox](https://codesandbox.io/s/cocky-lake-9jy0d).
There is also a full suite of Storybook stories, which can be run locally:
```
npm run storybook
```
## Basic Usage
```jsx
import React from "react";
import { Crop, Preview } from "react-simple-crop";
export const App = () => {
const imageRef = React.createRef();
const [value, setValue] = React.useState({
x: 0,
y: 0,
width: 0,
height: 0
});
return (
<>
setValue({ ...value, ...crop })}
ref={imageRef}
src={"..."}
value={value}
/>
{filePreview && }
>
);
};
```
## Components
### ``
Displays an image with a crop area overlay.
This crop area can be drawn, moved or resized, using mouse click, touch, or keyboard arrow events.
The `onChange` callback will fire any time the coordinates or size of the crop area change.
You must then update the local parent component state with the new `value` to see these changes reflected in the DOM.
#### How to use
```jsx
import { Crop } from "react-simple-crop";
/* ... */
const [value, setValue] = React.useState({
x: 0,
y: 0,
width: 0,
height: 0
});
setValue({ ...value, ...crop })}
src="..."
value={value}
/>;
```
#### Props
| Prop | Required | Type | Description |
| --------------- | :------: | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **onChange** | ✓ | `({ x: number; y: number; width: number; height: number; }) => void` | Callback which is fired any time the coordinates or size of the crop area change. |
| **src** | ✓ | `string` | Source attribute which is passed to the image element. |
| **value** | ✓ | `{ x: number; y: number; width: number; height: number; }` | Percentage coordinates and size of the crop area. You can also use this prop to initialize the size of the crop on the first render. |
| **aspectRatio** | | `[number, number]` | Restricts the ability to draw or resize a crop area to specific dimensions. |
| **alt** | | `string` | Alt attribute which is passed to the image element. |
| **className** | | `string` | Class name attribute passed to the containing element of the image and crop area. |
| **crossOrigin** | | `"anonymous" | "use-credentials"` | Cross origin attribute which is passed to the image element. |
| **maxHeight** | | `number` | Restricts the height of the crop area to a maximum percentage of the image element. |
| **maxWidth** | | `number` | Restricts the width of the crop area to a maximum percentage of the image element. |
| **minHeight** | | `number` | Restricts the height of the crop area to a minimum percentage of the image element. |
| **minWidth** | | `number` | Restricts the width of the crop area to a minimum percentage of the image element. |
| **onComplete** | | `() => void` | Callback which is fired any time the crop area finishes being drawn, moved by mouse or keyboard, or resized. |
| **onStart** | | `() => void` | Callback which is fired any time the crop area starts being drawn, moved by mouse or keyboard, or resized. |
| **ref** | | `{ current: HTMLImageElement }` | React ref object which is passed to the image element, and also needs to be passed to the `` component. This is used to draw the preview image. |
### ``
Displays a new preview image of the currently selected crop area. This image can then be saved as its own file.
#### How to use
```jsx
import { Crop, Preview } from "react-simple-crop";
/* ... */
const imageRef = React.createRef();
const [value, setValue] = React.useState({
x: 0,
y: 0,
width: 0,
height: 0
});
setValue({ ...value, ...crop })}
ref={imageRef}
src="..."
value={value}
/>
```
#### Props
| Prop | Required | Type | Description |
| ------------ | :------: | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **ref** | ✓ | `{ current: HTMLImageElement }` | React ref object of the `` component image element. This is used to draw the preview image. |
| **value** | ✓ | `{ x: number; y: number; width: number; height: number; }` | Percentage coordinates and size of the crop area. |
| **fileType** | | `string` | File type of the preview image (i.e. `image/jpeg`, `image/png`, or `image/gif`). |
Also accepts any HTML image attributes as props (i.e. `alt`, `crossOrigin` or `style`), apart from `src`, which is used internally by this component.
## Testing
There are no unit tests. Instead, we use end-to-end tests.
We require an actual DOM, versus an emulated DOM like [JSDOM](https://github.com/jsdom/jsdom), which is often used with unit testing libraries, to be able to easily compute image sizes and positions.
To run the Cypress E2E tests locally, first ensure the Storybook server is running:
```
npm run storybook
```
Then, in another terminal:
```
npm run cypress:open
```