0
# ngx-image-cropper
1

2
ngx-image-cropper provides a comprehensive image cropping component for Angular applications, enabling developers to integrate interactive image cropping functionality with extensive customization options. It offers a feature-rich API supporting multiple input methods, various output formats, aspect ratio controls, resize capabilities, and advanced features like canvas rotation, image transformation, and accessibility compliance.
3

4
## Package Information
5

6
- **Package Name**: ngx-image-cropper
7
- **Package Type**: npm
8
- **Language**: TypeScript (Angular)
9
- **Installation**: `npm install ngx-image-cropper`
10
- **Angular Version**: >=17.3.0
11

12
## Core Imports
13

14
```typescript
15
import { ImageCropperComponent } from "ngx-image-cropper";
16
```
17

18
For additional services and types:
19

20
```typescript
21
import { 
22
  ImageCropperComponent,
23
  CropService,
24
  LoadImageService,
25
  type CropperOptions,
26
  type ImageCroppedEvent,
27
  type CropperPosition,
28
  type ImageTransform,
29
  type LoadedImage,
30
  base64ToFile,
31
  resizeCanvas
32
} from "ngx-image-cropper";
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { Component } from '@angular/core';
39
import { ImageCropperComponent, ImageCroppedEvent } from 'ngx-image-cropper';
40

41
@Component({
42
  selector: 'app-cropper',
43
  standalone: true,
44
  imports: [ImageCropperComponent],
45
  template: `
46
    <image-cropper
47
      [imageChangedEvent]="imageChangedEvent"
48
      [maintainAspectRatio]="true"
49
      [aspectRatio]="4 / 3"
50
      [resizeToWidth]="256"
51
      format="png"
52
      (imageCropped)="imageCropped($event)"
53
      (imageLoaded)="imageLoaded()"
54
      (loadImageFailed)="loadImageFailed()">
55
    </image-cropper>
56
  `
57
})
58
export class CropperComponent {
59
  imageChangedEvent: Event | null = null;
60

61
  onFileChange(event: Event): void {
62
    this.imageChangedEvent = event;
63
  }
64

65
  imageCropped(event: ImageCroppedEvent): void {
66
    // event.base64 contains the cropped image as base64
67
    // event.blob contains the cropped image as Blob
68
    // event.objectUrl contains the cropped image as object URL
69
    console.log('Cropped image:', event);
70
  }
71

72
  imageLoaded(): void {
73
    console.log('Image loaded successfully');
74
  }
75

76
  loadImageFailed(): void {
77
    console.log('Image load failed');
78
  }
79
}
80
```
81

82
## Architecture
83

84
ngx-image-cropper is built around several key components:
85

86
- **ImageCropperComponent**: Main Angular component providing the interactive cropping interface
87
- **CropService**: Handles the actual image cropping operations and canvas manipulations
88
- **LoadImageService**: Manages image loading from various sources (File, URL, base64) with transformation support
89
- **Utility Functions**: Helper functions for common operations like base64 conversion and canvas resizing
90
- **Type System**: Comprehensive TypeScript interfaces for all configuration options and event data
91
- **EXIF Support**: Automatic handling of image orientation based on EXIF data
92

93
## Capabilities
94

95
### Image Cropper Component
96

97
The main interactive cropping component with extensive configuration options and event handling for complete crop lifecycle management.
98

99
```typescript { .api }
100
@Component({
101
  selector: 'image-cropper',
102
  standalone: true
103
})
104
export class ImageCropperComponent {
105
  // Input properties for image sources
106
  @Input() imageChangedEvent?: Event | null;
107
  @Input() imageURL?: string;
108
  @Input() imageBase64?: string;
109
  @Input() imageFile?: File;
110
  @Input() imageAltText?: string;
111

112
  // Configuration options
113
  @Input() options?: Partial<CropperOptions>;
114
  @Input() output?: 'blob' | 'base64';
115
  @Input() format?: OutputFormat;
116
  @Input() autoCrop?: boolean;
117
  @Input() maintainAspectRatio?: boolean;
118
  @Input() aspectRatio?: number;
119
  @Input() resizeToWidth?: number;
120
  @Input() resizeToHeight?: number;
121

122
  // Output events
123
  readonly imageCropped = output<ImageCroppedEvent>();
124
  readonly imageLoaded = output<LoadedImage>();
125
  readonly cropperReady = output<Dimensions>();
126
  readonly loadImageFailed = output<void>();
127

128
  // Public methods
129
  crop(): ImageCroppedEvent | null;
130
  crop(output: 'base64'): ImageCroppedEvent | null;
131
  crop(output: 'blob'): Promise<ImageCroppedEvent> | null;
132
  resetCropperPosition(): void;
133
}
134
```
135

136
[Image Cropper Component](./image-cropper-component.md)
137

138
### Crop Service
139

140
Service for performing the actual image cropping operations with canvas manipulation and format conversion.
141

142
```typescript { .api }
143
export class CropService {
144
  crop(input: CropInput, output: 'blob'): Promise<ImageCroppedEvent> | null;
145
  crop(input: CropInput, output: 'base64'): ImageCroppedEvent | null;
146
  getResizeRatio(width: number, height: number, options?: ResizeOptions): number;
147
  getQuality(options?: { imageQuality?: number }): number;
148
}
149
```
150

151
[Crop Service](./crop-service.md)
152

153
### Load Image Service
154

155
Service for loading and transforming images from various sources including files, URLs, and base64 strings.
156

157
```typescript { .api }
158
export class LoadImageService {
159
  loadImageFile(file: File, options: LoadImageOptions): Promise<LoadedImage>;
160
  loadImageFromURL(url: string, options: LoadImageOptions): Promise<LoadedImage>;
161
  loadBase64Image(imageBase64: string, options: LoadImageOptions): Promise<LoadedImage>;
162
  transformLoadedImage(loadedImage: Partial<LoadedImage>, options: LoadImageOptions, forceTransform?: boolean): Promise<LoadedImage>;
163
}
164
```
165

166
[Load Image Service](./load-image-service.md)
167

168
### Utility Functions
169

170
Helper functions for common image manipulation tasks.
171

172
```typescript { .api }
173
function base64ToFile(base64Image: string): Blob;
174
function resizeCanvas(canvas: HTMLCanvasElement, width: number, height: number): void;
175
```
176

177
[Utility Functions](./utility-functions.md)
178

179
## Core Types
180

181
```typescript { .api }
182
interface ImageCroppedEvent {
183
  base64?: string | null;
184
  blob?: Blob | null;
185
  objectUrl?: string | null;
186
  width: number;
187
  height: number;
188
  cropperPosition: CropperPosition;
189
  imagePosition: CropperPosition;
190
  offsetImagePosition?: CropperPosition;
191
}
192

193
interface CropperPosition {
194
  x1: number;
195
  y1: number;
196
  x2: number;
197
  y2: number;
198
}
199

200
interface ImageTransform {
201
  scale?: number;
202
  rotate?: number;
203
  flipH?: boolean;
204
  flipV?: boolean;
205
  translateH?: number;
206
  translateV?: number;
207
  translateUnit?: '%' | 'px';
208
}
209

210
interface Dimensions {
211
  width: number;
212
  height: number;
213
}
214

215
interface LoadedImage {
216
  original: {
217
    objectUrl: string;
218
    image: HTMLImageElement;
219
    size: Dimensions;
220
  };
221
  transformed: {
222
    objectUrl: string;
223
    image: HTMLImageElement;
224
    size: Dimensions;
225
  };
226
  exifTransform: ExifTransform;
227
}
228

229
interface LoadImageOptions {
230
  format?: OutputFormat;
231
  checkImageType?: boolean;
232
  canvasRotation?: number;
233
  containWithinAspectRatio?: boolean;
234
  aspectRatio?: number;
235
}
236

237
interface CropInput {
238
  loadedImage: LoadedImage;
239
  cropper: CropperPosition;
240
  maxSize: Dimensions;
241
  transform?: ImageTransform;
242
  options?: {
243
    backgroundColor?: string;
244
    containWithinAspectRatio?: boolean;
245
    maintainAspectRatio?: boolean;
246
    aspectRatio?: number;
247
    format?: OutputFormat;
248
    canvasRotation?: number;
249
    imageQuality?: number;
250
    resizeToWidth?: number;
251
    resizeToHeight?: number;
252
    onlyScaleDown?: boolean;
253
  };
254
}
255

256
interface ExifTransform {
257
  rotate: number;
258
  flip: boolean;
259
}
260

261
interface CropperOptions {
262
  format: OutputFormat;
263
  output: OutputType;
264
  autoCrop: boolean;
265
  maintainAspectRatio: boolean;
266
  resetCropOnAspectRatioChange: boolean;
267
  aspectRatio: number;
268
  resizeToWidth: number;
269
  resizeToHeight: number;
270
  cropperMinWidth: number;
271
  cropperMinHeight: number;
272
  cropperMaxHeight: number;
273
  cropperMaxWidth: number;
274
  cropperStaticWidth: number;
275
  cropperStaticHeight: number;
276
  canvasRotation: number;
277
  roundCropper: boolean;
278
  onlyScaleDown: boolean;
279
  imageQuality: number;
280
  backgroundColor: string | undefined;
281
  containWithinAspectRatio: boolean;
282
  hideResizeSquares: boolean;
283
  alignImage: 'left' | 'center';
284
  cropperFrameAriaLabel: string | undefined;
285
  checkImageType: boolean;
286
}
287

288
type OutputFormat = 'png' | 'jpeg' | 'bmp' | 'webp' | 'ico';
289
type OutputType = 'base64' | 'blob';
290
```