0
# React Component
1

2
The ReactCrop component is the main interface for image cropping functionality. It's a controlled React component that requires the parent to manage crop state through callbacks.
3

4
## Capabilities
5

6
### ReactCrop Component
7

8
The main React component providing complete cropping functionality with drag handles, touch support, and keyboard accessibility.
9

10
```typescript { .api }
11
/**
12
 * Main React component for image cropping functionality
13
 * Supports touch interactions, keyboard navigation, and comprehensive customization
14
 */
15
class ReactCrop extends PureComponent<ReactCropProps, ReactCropState> {
16
  static xOrds: string[];
17
  static yOrds: string[];
18
  static xyOrds: string[];
19
  static nudgeStep: number;
20
  static nudgeStepMedium: number;
21
  static nudgeStepLarge: number;
22
}
23

24
interface ReactCropProps {
25
  /** Current crop state - component is controlled via this prop */
26
  crop?: Crop;
27
  /** Required callback fired on every crop change */
28
  onChange: (crop: PixelCrop, percentageCrop: PercentCrop) => void;
29
  /** Elements to crop (typically img or video elements) */
30
  children?: React.ReactNode;
31
  /** Fixed aspect ratio for the crop (e.g., 1 for square, 16/9 for landscape) */
32
  aspect?: number;
33
  /** Show crop as circle instead of rectangle */
34
  circularCrop?: boolean;
35
  /** Disable all crop interactions */
36
  disabled?: boolean;
37
  /** Prevent resize/create but allow dragging existing crop */
38
  locked?: boolean;
39
  /** Minimum crop width in pixels */
40
  minWidth?: number;
41
  /** Minimum crop height in pixels */
42
  minHeight?: number;
43
  /** Maximum crop width in pixels */
44
  maxWidth?: number;
45
  /** Maximum crop height in pixels */
46
  maxHeight?: number;
47
  /** Callback fired when drag/resize operation completes */
48
  onComplete?: (crop: PixelCrop, percentageCrop: PercentCrop) => void;
49
  /** Callback fired when drag operation starts */
50
  onDragStart?: (e: PointerEvent) => void;
51
  /** Callback fired when drag operation ends */
52
  onDragEnd?: (e: PointerEvent) => void;
53
  /** Custom component rendered inside crop selection area */
54
  renderSelectionAddon?: (state: ReactCropState) => React.ReactNode;
55
  /** Show rule of thirds grid lines */
56
  ruleOfThirds?: boolean;
57
  /** Prevent crop deselection when clicking outside */
58
  keepSelection?: boolean;
59
  /** Accessibility labels for screen readers */
60
  ariaLabels?: AriaLabels;
61
  /** CSS classes to apply to component */
62
  className?: string;
63
  /** Inline styles for component */
64
  style?: React.CSSProperties;
65
}
66

67
interface ReactCropState {
68
  /** Whether crop is currently being manipulated */
69
  cropIsActive: boolean;
70
  /** Whether user is drawing a new crop selection */
71
  newCropIsBeingDrawn: boolean;
72
}
73
```
74

75
**Basic Usage:**
76

77
```typescript
78
import React, { useState } from "react";
79
import ReactCrop, { Crop, PixelCrop, PercentCrop } from "react-image-crop";
80

81
function ImageCropper() {
82
  const [crop, setCrop] = useState<Crop>();
83

84
  return (
85
    <ReactCrop
86
      crop={crop}
87
      onChange={(pixelCrop: PixelCrop, percentCrop: PercentCrop) => {
88
        setCrop(pixelCrop);
89
      }}
90
      onComplete={(pixelCrop: PixelCrop, percentCrop: PercentCrop) => {
91
        console.log('Crop completed:', pixelCrop);
92
      }}
93
    >
94
      <img src="path/to/image.jpg" alt="Crop me" />
95
    </ReactCrop>
96
  );
97
}
98
```
99

100
**Advanced Usage with Fixed Aspect Ratio:**
101

102
```typescript
103
import React, { useState } from "react";
104
import ReactCrop, { Crop, PixelCrop, PercentCrop, makeAspectCrop, centerCrop } from "react-image-crop";
105

106
function SquareCropper() {
107
  const [crop, setCrop] = useState<Crop>();
108

109
  const onImageLoad = (e: React.SyntheticEvent<HTMLImageElement>) => {
110
    const { naturalWidth: width, naturalHeight: height } = e.currentTarget;
111
    
112
    // Create a centered square crop
113
    const newCrop = centerCrop(
114
      makeAspectCrop({ unit: '%' }, 1, width, height),
115
      width,
116
      height
117
    );
118
    
119
    setCrop(newCrop);
120
  };
121

122
  return (
123
    <ReactCrop
124
      crop={crop}
125
      aspect={1} // Square aspect ratio
126
      onChange={(_, percentCrop) => setCrop(percentCrop)}
127
    >
128
      <img 
129
        src="path/to/image.jpg" 
130
        alt="Crop me" 
131
        onLoad={onImageLoad}
132
      />
133
    </ReactCrop>
134
  );
135
}
136
```
137

138
**Circular Crop Usage:**
139

140
```typescript
141
import React, { useState } from "react";
142
import ReactCrop, { Crop, PixelCrop, PercentCrop } from "react-image-crop";
143

144
function CircularCropper() {
145
  const [crop, setCrop] = useState<Crop>({
146
    unit: '%',
147
    x: 25,
148
    y: 25,
149
    width: 50,
150
    height: 50,
151
  });
152

153
  return (
154
    <ReactCrop
155
      crop={crop}
156
      circularCrop={true}
157
      aspect={1} // Square aspect for perfect circle
158
      onChange={(_, percentCrop) => setCrop(percentCrop)}
159
    >
160
      <img src="path/to/image.jpg" alt="Crop me" />
161
    </ReactCrop>
162
  );
163
}
164
```
165

166
### Component Static Properties
167

168
Static properties providing constants for crop manipulation and keyboard interaction.
169

170
```typescript { .api }
171
/**
172
 * Static properties on ReactCrop class
173
 */
174
class ReactCrop {
175
  /** X-axis drag handle ordinates: ['e', 'w'] */
176
  static xOrds: string[];
177
  /** Y-axis drag handle ordinates: ['n', 's'] */
178
  static yOrds: string[];
179
  /** Corner drag handle ordinates: ['nw', 'ne', 'se', 'sw'] */
180
  static xyOrds: string[];
181
  /** Default keyboard nudge distance: 1 pixel */
182
  static nudgeStep: number;
183
  /** Medium keyboard nudge distance (Shift key): 10 pixels */
184
  static nudgeStepMedium: number;
185
  /** Large keyboard nudge distance (Ctrl/Cmd key): 100 pixels */
186
  static nudgeStepLarge: number;
187
}
188
```
189

190
### Keyboard Accessibility
191

192
The component supports full keyboard navigation:
193

194
- **Arrow keys**: Move crop selection by `nudgeStep` pixels
195
- **Shift + Arrow keys**: Move crop selection by `nudgeStepMedium` pixels  
196
- **Ctrl/Cmd + Arrow keys**: Move crop selection by `nudgeStepLarge` pixels
197
- **Tab**: Navigate between drag handles
198
- **Enter/Space**: Activate drag handles for keyboard resizing
199

200
### Touch Support
201

202
The component automatically handles touch interactions:
203

204
- **Touch drag**: Move crop selection
205
- **Pinch resize**: Resize crop selection (on drag handles)
206
- **Touch accessibility**: Works with screen readers and assistive touch
207

208
### Styling
209

210
The component includes default CSS classes for styling:
211

212
- `.ReactCrop`: Main container
213
- `.ReactCrop--active`: Applied during crop manipulation
214
- `.ReactCrop--disabled`: Applied when disabled prop is true
215
- `.ReactCrop--locked`: Applied when locked prop is true
216
- `.ReactCrop--circular-crop`: Applied when circularCrop prop is true
217
- `.ReactCrop--fixed-aspect`: Applied when aspect prop is set
218
- `.ReactCrop--rule-of-thirds`: Applied when ruleOfThirds prop is true
219

220
Import the CSS file for default styling:
221

222
```css
223
@import "react-image-crop/dist/ReactCrop.css";
224
```
225

226
Or use the SCSS source for customization:
227

228
```scss
229
@import "react-image-crop/src/ReactCrop.scss";
230
```