0
# React Image Crop
1

2
React Image Crop is a responsive image cropping tool for React with zero dependencies. It provides a complete cropping interface with support for pixel and percentage coordinates, touch interactions, keyboard accessibility, and various cropping modes including fixed aspect ratios and circular crops.
3

4
## Package Information
5

6
- **Package Name**: react-image-crop
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-image-crop`
10

11
## Core Imports
12

13
```typescript
14
// Default import (recommended)
15
import ReactCrop, { Crop, PixelCrop, PercentCrop, AriaLabels } from "react-image-crop";
16
import "react-image-crop/dist/ReactCrop.css";
17

18
// Named import (alternative)
19
import { ReactCrop, Crop, PixelCrop, PercentCrop, AriaLabels } from "react-image-crop";
20

21
// For legacy compatibility
22
import { Component } from "react-image-crop"; // Same as ReactCrop
23
```
24

25
**CSS Import Options:**
26

27
```typescript
28
// Compiled CSS (recommended for most projects)
29
import "react-image-crop/dist/ReactCrop.css";
30

31
// SCSS source (for projects with SCSS build setup)
32
import "react-image-crop/src/ReactCrop.scss";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const ReactCrop = require("react-image-crop").default;
39
// or
40
const { ReactCrop, Component } = require("react-image-crop");
41
```
42

43
You can also import individual utilities:
44

45
```typescript
46
import { 
47
  makeAspectCrop, 
48
  centerCrop, 
49
  convertToPixelCrop, 
50
  convertToPercentCrop 
51
} from "react-image-crop";
52
```
53

54
## Basic Usage
55

56
```typescript
57
import React, { useState } from "react";
58
import ReactCrop, { Crop, PixelCrop, PercentCrop } from "react-image-crop";
59
import "react-image-crop/dist/ReactCrop.css";
60

61
function CropDemo({ src }: { src: string }) {
62
  const [crop, setCrop] = useState<Crop>();
63

64
  return (
65
    <ReactCrop 
66
      crop={crop} 
67
      onChange={(pixelCrop: PixelCrop, percentCrop: PercentCrop) => setCrop(pixelCrop)}
68
    >
69
      <img src={src} alt="Crop me" />
70
    </ReactCrop>
71
  );
72
}
73
```
74

75
## Architecture
76

77
React Image Crop is built around several key components:
78

79
- **ReactCrop Component**: Main React component that handles all cropping interactions
80
- **Crop Types**: TypeScript interfaces defining crop coordinates in pixels or percentages
81
- **Utility Functions**: Helper functions for crop manipulation, aspect ratio enforcement, and coordinate conversion
82
- **Event System**: Comprehensive callback system for drag events and crop changes
83
- **Accessibility**: Full keyboard navigation and screen reader support
84

85
The library uses a controlled component pattern where the parent component manages crop state through the required `onChange` callback.
86

87
## Capabilities
88

89
### React Component
90

91
The main ReactCrop component providing the complete cropping interface with drag handles, keyboard navigation, and comprehensive customization options.
92

93
```typescript { .api }
94
interface ReactCropProps {
95
  crop?: Crop;
96
  onChange: (crop: PixelCrop, percentageCrop: PercentCrop) => void;
97
  children?: React.ReactNode;
98
  aspect?: number;
99
  circularCrop?: boolean;
100
  disabled?: boolean;
101
  locked?: boolean;
102
  minWidth?: number;
103
  minHeight?: number;
104
  maxWidth?: number;
105
  maxHeight?: number;
106
  onComplete?: (crop: PixelCrop, percentageCrop: PercentCrop) => void;
107
  onDragStart?: (e: PointerEvent) => void;
108
  onDragEnd?: (e: PointerEvent) => void;
109
  renderSelectionAddon?: (state: ReactCropState) => React.ReactNode;
110
  ruleOfThirds?: boolean;
111
  keepSelection?: boolean;
112
  ariaLabels?: AriaLabels;
113
  className?: string;
114
  style?: React.CSSProperties;
115
}
116

117
class ReactCrop extends PureComponent<ReactCropProps, ReactCropState> {}
118
```
119

120
[React Component](./component.md)
121

122
### Crop Types
123

124
TypeScript interfaces and types for defining crop coordinates and dimensions in both pixel and percentage units.
125

126
```typescript { .api }
127
interface Crop {
128
  x: number;
129
  y: number;
130
  width: number;
131
  height: number;
132
  unit: 'px' | '%';
133
}
134

135
interface PixelCrop extends Crop {
136
  unit: 'px';
137
}
138

139
interface PercentCrop extends Crop {
140
  unit: '%';
141
}
142

143
type Ords = 'n' | 's' | 'e' | 'w' | 'nw' | 'ne' | 'se' | 'sw';
144
```
145

146
[Crop Types](./types.md)
147

148
### Utility Functions
149

150
Helper functions for crop manipulation including aspect ratio enforcement, coordinate conversion, and crop positioning utilities.
151

152
```typescript { .api }
153
function makeAspectCrop(
154
  crop: Partial<Crop>, 
155
  aspect: number, 
156
  containerWidth: number, 
157
  containerHeight: number
158
): Crop;
159

160
function centerCrop(
161
  crop: Partial<Crop>, 
162
  containerWidth: number, 
163
  containerHeight: number
164
): Crop;
165

166
function convertToPixelCrop(
167
  crop: Partial<Crop>, 
168
  containerWidth: number, 
169
  containerHeight: number
170
): PixelCrop;
171

172
function convertToPercentCrop(
173
  crop: Partial<Crop>, 
174
  containerWidth: number, 
175
  containerHeight: number
176
): PercentCrop;
177
```
178

179
[Utility Functions](./utils.md)