0
# Crop Types
1

2
TypeScript interfaces and type definitions for crop coordinates, dimensions, and drag handle ordinates used throughout the react-image-crop library.
3

4
## Capabilities
5

6
### Core Crop Interfaces
7

8
Basic interfaces defining crop coordinates and dimensions in both pixel and percentage units.
9

10
```typescript { .api }
11
/**
12
 * Base crop interface defining position, size, and coordinate units
13
 */
14
interface Crop {
15
  /** X coordinate of crop's top-left corner */
16
  x: number;
17
  /** Y coordinate of crop's top-left corner */
18
  y: number;
19
  /** Width of the crop selection */
20
  width: number;
21
  /** Height of the crop selection */
22
  height: number;
23
  /** Coordinate unit system: pixels or percentage */
24
  unit: 'px' | '%';
25
}
26

27
/**
28
 * Crop with pixel-based coordinates
29
 * Used for precise positioning and sizing
30
 */
31
interface PixelCrop extends Crop {
32
  unit: 'px';
33
}
34

35
/**
36
 * Crop with percentage-based coordinates  
37
 * Used for responsive layouts and relative positioning
38
 */
39
interface PercentCrop extends Crop {
40
  unit: '%';
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import { Crop, PixelCrop, PercentCrop } from "react-image-crop";
48

49
// Pixel-based crop (absolute positioning)
50
const pixelCrop: PixelCrop = {
51
  unit: 'px',
52
  x: 100,
53
  y: 50,
54
  width: 200,
55
  height: 150,
56
};
57

58
// Percentage-based crop (relative positioning)
59
const percentCrop: PercentCrop = {
60
  unit: '%',
61
  x: 25,     // 25% from left
62
  y: 12.5,   // 12.5% from top
63
  width: 50, // 50% of container width
64
  height: 37.5, // 37.5% of container height
65
};
66

67
// Generic crop (can be either unit type)
68
const genericCrop: Crop = {
69
  unit: '%',
70
  x: 10,
71
  y: 10,
72
  width: 80,
73
  height: 80,
74
};
75
```
76

77
### Drag Handle Ordinates
78

79
Type definitions for drag handle positions used in crop manipulation and keyboard navigation.
80

81
```typescript { .api }
82
/**
83
 * X-axis drag handle positions (east/west)
84
 */
85
type XOrds = 'e' | 'w';
86

87
/**
88
 * Y-axis drag handle positions (north/south)
89
 */
90
type YOrds = 'n' | 's';
91

92
/**
93
 * Corner drag handle positions (diagonal)
94
 */
95
type XYOrds = 'nw' | 'ne' | 'se' | 'sw';
96

97
/**
98
 * All possible drag handle positions
99
 * Used for resize operations and keyboard navigation
100
 */
101
type Ords = XOrds | YOrds | XYOrds;
102
```
103

104
**Ordinate Meanings:**
105

106
- `'n'` - North (top edge)
107
- `'s'` - South (bottom edge)
108
- `'e'` - East (right edge)
109
- `'w'` - West (left edge)
110
- `'nw'` - Northwest (top-left corner)
111
- `'ne'` - Northeast (top-right corner)
112
- `'se'` - Southeast (bottom-right corner)
113
- `'sw'` - Southwest (bottom-left corner)
114

115
**Usage in Drag Operations:**
116

117
```typescript
118
import { Ords } from "react-image-crop";
119

120
// Handle type is automatically inferred based on which drag handle is used
121
function handleDragStart(ord: Ords) {
122
  switch (ord) {
123
    case 'nw':
124
      console.log('Dragging top-left corner');
125
      break;
126
    case 'n':
127
      console.log('Dragging top edge');
128
      break;
129
    case 'ne':
130
      console.log('Dragging top-right corner');
131
      break;
132
    // ... other cases
133
  }
134
}
135
```
136

137
### Type Guards and Utilities
138

139
Helper functions for working with crop types and ensuring type safety.
140

141
```typescript { .api }
142
/**
143
 * Default pixel crop with zero dimensions
144
 * Useful as a starting point for new crops
145
 */
146
const defaultCrop: PixelCrop;
147

148
/**
149
 * Utility function to compare crop objects for equality
150
 * Handles partial crop objects safely
151
 */
152
function areCropsEqual(cropA: Partial<Crop>, cropB: Partial<Crop>): boolean;
153
```
154

155
**Type Guard Usage:**
156

157
```typescript
158
import { Crop, PixelCrop, PercentCrop, defaultCrop, areCropsEqual } from "react-image-crop";
159

160
// Type checking
161
function isPixelCrop(crop: Crop): crop is PixelCrop {
162
  return crop.unit === 'px';
163
}
164

165
function isPercentCrop(crop: Crop): crop is PercentCrop {
166
  return crop.unit === '%';
167
}
168

169
// Using default crop
170
const newCrop: PixelCrop = { ...defaultCrop, width: 100, height: 100 };
171

172
// Comparing crops
173
const crop1: Crop = { unit: 'px', x: 10, y: 10, width: 50, height: 50 };
174
const crop2: Crop = { unit: 'px', x: 10, y: 10, width: 50, height: 50 };
175

176
if (areCropsEqual(crop1, crop2)) {
177
  console.log('Crops are identical');
178
}
179
```
180

181
### Component State Types
182

183
Interfaces defining the internal state of the ReactCrop component.
184

185
```typescript { .api }
186
/**
187
 * Internal state interface for ReactCrop component
188
 * Tracks current interaction state
189
 */
190
interface ReactCropState {
191
  /** Whether crop is currently being manipulated (dragging/resizing) */
192
  cropIsActive: boolean;
193
  /** Whether user is in the process of drawing a new crop selection */
194
  newCropIsBeingDrawn: boolean;
195
}
196

197
/**
198
 * Accessibility labels interface for screen readers
199
 * Provides custom labels for crop area and drag handles
200
 */
201
interface AriaLabels {
202
  /** Label for the main crop selection area */
203
  cropArea: string;
204
  /** Label for northwest (top-left) drag handle */
205
  nwDragHandle: string;
206
  /** Label for north (top) drag handle */
207
  nDragHandle: string;
208
  /** Label for northeast (top-right) drag handle */
209
  neDragHandle: string;
210
  /** Label for east (right) drag handle */
211
  eDragHandle: string;
212
  /** Label for southeast (bottom-right) drag handle */
213
  seDragHandle: string;
214
  /** Label for south (bottom) drag handle */
215
  sDragHandle: string;
216
  /** Label for southwest (bottom-left) drag handle */
217
  swDragHandle: string;
218
  /** Label for west (left) drag handle */
219
  wDragHandle: string;
220
}
221
```
222

223
### Advanced Type Patterns
224

225
Common patterns for working with crop types in TypeScript applications.
226

227
**Partial Crops:**
228

229
```typescript
230
import { Crop, PixelCrop } from "react-image-crop";
231

232
// Partial crop for initialization
233
const partialCrop: Partial<Crop> = {
234
  unit: '%',
235
  width: 50,
236
  height: 50,
237
  // x and y will be calculated by utility functions
238
};
239

240
// Creating crops with required and optional properties
241
function createCrop(required: Pick<Crop, 'unit'>, optional?: Partial<Omit<Crop, 'unit'>>): Crop {
242
  return {
243
    x: 0,
244
    y: 0,
245
    width: 0,
246
    height: 0,
247
    ...optional,
248
    unit: required.unit,
249
  };
250
}
251
```
252

253
**Generic Crop Functions:**
254

255
```typescript
256
import { Crop, PixelCrop, PercentCrop } from "react-image-crop";
257

258
// Function that preserves crop unit type
259
function scaleCrop<T extends Crop>(crop: T, scaleFactor: number): T {
260
  return {
261
    ...crop,
262
    x: crop.x * scaleFactor,
263
    y: crop.y * scaleFactor,
264
    width: crop.width * scaleFactor,
265
    height: crop.height * scaleFactor,
266
  };
267
}
268

269
// Usage maintains type safety
270
const pixelCrop: PixelCrop = { unit: 'px', x: 10, y: 10, width: 100, height: 100 };
271
const scaledPixelCrop: PixelCrop = scaleCrop(pixelCrop, 2); // Still PixelCrop
272

273
const percentCrop: PercentCrop = { unit: '%', x: 10, y: 10, width: 50, height: 50 };
274
const scaledPercentCrop: PercentCrop = scaleCrop(percentCrop, 1.5); // Still PercentCrop
275
```