0
# Image Cropper Component
1

2
The ImageCropperComponent provides an interactive image cropping interface with extensive customization options, multiple input methods, and comprehensive event handling.
3

4
## Capabilities
5

6
### Component Configuration
7

8
The main Angular component with complete cropping functionality.
9

10
```typescript { .api }
11
@Component({
12
  selector: 'image-cropper',
13
  standalone: true,
14
  imports: [NgIf]
15
})
16
export class ImageCropperComponent implements OnChanges, OnInit, OnDestroy {
17
  // Image Input Properties
18
  @Input() imageChangedEvent?: Event | null;
19
  @Input() imageURL?: string;
20
  @Input() imageBase64?: string;
21
  @Input() imageFile?: File;
22
  @Input() imageAltText?: string;
23

24
  // Configuration Properties
25
  @Input() options?: Partial<CropperOptions>;
26
  @Input() cropperFrameAriaLabel?: string;
27
  @Input() output?: 'blob' | 'base64';
28
  @Input() format?: OutputFormat;
29
  @Input() autoCrop?: boolean;
30
  @Input() cropper?: CropperPosition;
31
  @Input() transform?: ImageTransform;
32
  @Input() maintainAspectRatio?: boolean;
33
  @Input() aspectRatio?: number;
34
  @Input() resetCropOnAspectRatioChange?: boolean;
35

36
  // Resize Properties
37
  @Input() resizeToWidth?: number;
38
  @Input() resizeToHeight?: number;
39
  @Input() cropperMinWidth?: number;
40
  @Input() cropperMinHeight?: number;
41
  @Input() cropperMaxHeight?: number;
42
  @Input() cropperMaxWidth?: number;
43
  @Input() cropperStaticWidth?: number;
44
  @Input() cropperStaticHeight?: number;
45

46
  // Display Properties
47
  @Input() canvasRotation?: number;
48
  @Input() initialStepSize?: number;
49
  @Input() roundCropper?: boolean;
50
  @Input() onlyScaleDown?: boolean;
51
  @Input() imageQuality?: number;
52
  @Input() backgroundColor?: string;
53
  @Input() containWithinAspectRatio?: boolean;
54
  @Input() hideResizeSquares?: boolean;
55
  @Input() allowMoveImage?: boolean;
56
  @Input() checkImageType?: boolean;
57
  @Input() alignImage?: 'left' | 'center';
58
  @Input() disabled?: boolean;
59
  @Input() hidden?: boolean;
60

61
  // Output Events
62
  readonly imageCropped = output<ImageCroppedEvent>();
63
  readonly startCropImage = output<void>();
64
  readonly imageLoaded = output<LoadedImage>();
65
  readonly cropperReady = output<Dimensions>();
66
  readonly loadImageFailed = output<void>();
67
  readonly transformChange = output<ImageTransform>();
68
  readonly cropperChange = output<CropperPosition>();
69

70
  // Public Methods
71
  crop(): ImageCroppedEvent | null;
72
  crop(output: 'base64'): ImageCroppedEvent | null;
73
  crop(output: 'blob'): Promise<ImageCroppedEvent> | null;
74
  resetCropperPosition(): void;
75
  keyboardAccess(event: KeyboardEvent): void;
76
}
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
import { Component } from '@angular/core';
83
import { ImageCropperComponent, ImageCroppedEvent } from 'ngx-image-cropper';
84

85
@Component({
86
  selector: 'app-advanced-cropper',
87
  standalone: true,
88
  imports: [ImageCropperComponent],
89
  template: `
90
    <image-cropper
91
      [imageFile]="selectedFile"
92
      [maintainAspectRatio]="true"
93
      [aspectRatio]="16 / 9"
94
      [resizeToWidth]="800"
95
      [resizeToHeight]="450"
96
      [roundCropper]="false"
97
      [onlyScaleDown]="true"
98
      [imageQuality]="90"
99
      [backgroundColor]="'#ffffff'"
100
      [hideResizeSquares]="false"
101
      [allowMoveImage]="true"
102
      [canvasRotation]="0"
103
      format="jpeg"
104
      output="blob"
105
      [autoCrop]="true"
106
      (imageCropped)="imageCropped($event)"
107
      (imageLoaded)="imageLoaded($event)"
108
      (cropperReady)="cropperReady($event)"
109
      (cropperChange)="cropperPositionChanged($event)"
110
      (transformChange)="transformChanged($event)"
111
      (loadImageFailed)="loadImageFailed()"
112
      (startCropImage)="startCropping()">
113
    </image-cropper>
114
  `
115
})
116
export class AdvancedCropperComponent {
117
  selectedFile: File | null = null;
118

119
  onFileSelected(event: Event): void {
120
    const input = event.target as HTMLInputElement;
121
    if (input.files && input.files[0]) {
122
      this.selectedFile = input.files[0];
123
    }
124
  }
125

126
  imageCropped(event: ImageCroppedEvent): void {
127
    if (event.blob) {
128
      // Handle blob result
129
      const formData = new FormData();
130
      formData.append('image', event.blob, 'cropped-image.jpeg');
131
      // Upload or process the blob
132
    }
133
  }
134

135
  imageLoaded(loadedImage: LoadedImage): void {
136
    console.log('Image loaded:', loadedImage.original.size);
137
  }
138

139
  cropperReady(dimensions: Dimensions): void {
140
    console.log('Cropper ready with dimensions:', dimensions);
141
  }
142

143
  cropperPositionChanged(position: CropperPosition): void {
144
    console.log('Cropper position changed:', position);
145
  }
146

147
  transformChanged(transform: ImageTransform): void {
148
    console.log('Image transform changed:', transform);
149
  }
150

151
  loadImageFailed(): void {
152
    console.error('Failed to load image');
153
  }
154

155
  startCropping(): void {
156
    console.log('Cropping operation started');
157
  }
158
}
159
```
160

161
### Input Properties
162

163
#### Image Sources
164

165
Properties for providing images to the cropper from different sources.
166

167
```typescript { .api }
168
/**
169
 * File input change event containing the selected image file
170
 */
171
@Input() imageChangedEvent?: Event | null;
172

173
/**
174
 * URL to load the image from
175
 */
176
@Input() imageURL?: string;
177

178
/**
179
 * Base64 encoded image string
180
 */
181
@Input() imageBase64?: string;
182

183
/**
184
 * File object containing image data
185
 */
186
@Input() imageFile?: File;
187

188
/**
189
 * Alt text for the image for accessibility
190
 */
191
@Input() imageAltText?: string;
192
```
193

194
#### Configuration Options
195

196
Properties for configuring cropper behavior and appearance.
197

198
```typescript { .api }
199
/**
200
 * Configuration options object containing cropper settings
201
 */
202
@Input() options?: Partial<CropperOptions>;
203

204
/**
205
 * ARIA label for the cropper frame for accessibility
206
 */
207
@Input() cropperFrameAriaLabel?: string;
208

209
/**
210
 * Preferred output format: 'blob' or 'base64'
211
 */
212
@Input() output?: 'blob' | 'base64';
213

214
/**
215
 * Image output format
216
 */
217
@Input() format?: OutputFormat;
218

219
/**
220
 * Automatically crop when image or cropper changes
221
 */
222
@Input() autoCrop?: boolean;
223

224
/**
225
 * Initial cropper position
226
 */
227
@Input() cropper?: CropperPosition;
228

229
/**
230
 * Image transformation settings
231
 */
232
@Input() transform?: ImageTransform;
233
```
234

235
#### Aspect Ratio Controls
236

237
Properties for controlling the cropper's aspect ratio behavior.
238

239
```typescript { .api }
240
/**
241
 * Maintain aspect ratio when resizing the cropper
242
 */
243
@Input() maintainAspectRatio?: boolean;
244

245
/**
246
 * Fixed aspect ratio (width/height)
247
 */
248
@Input() aspectRatio?: number;
249

250
/**
251
 * Reset crop area when aspect ratio changes
252
 */
253
@Input() resetCropOnAspectRatioChange?: boolean;
254
```
255

256
#### Size Controls
257

258
Properties for controlling cropper and output dimensions.
259

260
```typescript { .api }
261
/**
262
 * Target width for the output image (pixels)
263
 */
264
@Input() resizeToWidth?: number;
265

266
/**
267
 * Target height for the output image (pixels)
268
 */
269
@Input() resizeToHeight?: number;
270

271
/**
272
 * Minimum cropper width (pixels)
273
 */
274
@Input() cropperMinWidth?: number;
275

276
/**
277
 * Minimum cropper height (pixels)
278
 */
279
@Input() cropperMinHeight?: number;
280

281
/**
282
 * Maximum cropper height (pixels)
283
 */
284
@Input() cropperMaxHeight?: number;
285

286
/**
287
 * Maximum cropper width (pixels)
288
 */
289
@Input() cropperMaxWidth?: number;
290

291
/**
292
 * Fixed cropper width (pixels) - disables horizontal resizing
293
 */
294
@Input() cropperStaticWidth?: number;
295

296
/**
297
 * Fixed cropper height (pixels) - disables vertical resizing
298
 */
299
@Input() cropperStaticHeight?: number;
300
```
301

302
### Output Events
303

304
Events emitted during the cropping lifecycle.
305

306
```typescript { .api }
307
/**
308
 * Emitted when the image is cropped
309
 */
310
readonly imageCropped = output<ImageCroppedEvent>();
311

312
/**
313
 * Emitted when cropping operation starts
314
 */
315
readonly startCropImage = output<void>();
316

317
/**
318
 * Emitted when image loads successfully
319
 */
320
readonly imageLoaded = output<LoadedImage>();
321

322
/**
323
 * Emitted when cropper is ready for interaction
324
 */
325
readonly cropperReady = output<Dimensions>();
326

327
/**
328
 * Emitted when image loading fails
329
 */
330
readonly loadImageFailed = output<void>();
331

332
/**
333
 * Emitted when image transform changes (scale, rotation, etc.)
334
 */
335
readonly transformChange = output<ImageTransform>();
336

337
/**
338
 * Emitted when cropper position changes
339
 */
340
readonly cropperChange = output<CropperPosition>();
341
```
342

343
### Public Methods
344

345
Methods available for programmatic control of the cropper.
346

347
```typescript { .api }
348
/**
349
 * Crop the image with default output type
350
 * @returns ImageCroppedEvent with cropped image data or null if no image loaded
351
 */
352
crop(): ImageCroppedEvent | null;
353

354
/**
355
 * Crop the image to base64 format
356
 * @param output - Output type 'base64'
357
 * @returns ImageCroppedEvent with base64 data or null if no image loaded
358
 */
359
crop(output: 'base64'): ImageCroppedEvent | null;
360

361
/**
362
 * Crop the image to blob format
363
 * @param output - Output type 'blob'
364
 * @returns Promise resolving to ImageCroppedEvent with blob data or null if no image loaded
365
 */
366
crop(output: 'blob'): Promise<ImageCroppedEvent> | null;
367

368
/**
369
 * Reset the cropper to its default position and size
370
 */
371
resetCropperPosition(): void;
372

373
/**
374
 * Handle keyboard navigation events
375
 * @param event - KeyboardEvent for cropper navigation
376
 */
377
keyboardAccess(event: KeyboardEvent): void;
378
```
379

380
### Supporting Types
381

382
```typescript { .api }
383
interface CropperOptions {
384
  format: OutputFormat;
385
  output: OutputType;
386
  autoCrop: boolean;
387
  maintainAspectRatio: boolean;
388
  resetCropOnAspectRatioChange: boolean;
389
  aspectRatio: number;
390
  resizeToWidth: number;
391
  resizeToHeight: number;
392
  cropperMinWidth: number;
393
  cropperMinHeight: number;
394
  cropperMaxHeight: number;
395
  cropperMaxWidth: number;
396
  cropperStaticWidth: number;
397
  cropperStaticHeight: number;
398
  canvasRotation: number;
399
  roundCropper: boolean;
400
  onlyScaleDown: boolean;
401
  imageQuality: number;
402
  backgroundColor: string | undefined;
403
  containWithinAspectRatio: boolean;
404
  hideResizeSquares: boolean;
405
  alignImage: 'left' | 'center';
406
  cropperFrameAriaLabel: string | undefined;
407
  checkImageType: boolean;
408
}
409

410
type OutputFormat = 'png' | 'jpeg' | 'bmp' | 'webp' | 'ico';
411
```