or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

crop-service.mdimage-cropper-component.mdindex.mdload-image-service.mdutility-functions.md
tile.json

tessl/npm-ngx-image-cropper

An image cropper component for Angular applications with comprehensive cropping functionality

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ngx-image-cropper@9.1.x

To install, run

npx @tessl/cli install tessl/npm-ngx-image-cropper@9.1.0

index.mddocs/

ngx-image-cropper

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.

Package Information

  • Package Name: ngx-image-cropper
  • Package Type: npm
  • Language: TypeScript (Angular)
  • Installation: npm install ngx-image-cropper
  • Angular Version: >=17.3.0

Core Imports

import { ImageCropperComponent } from "ngx-image-cropper";

For additional services and types:

import { 
  ImageCropperComponent,
  CropService,
  LoadImageService,
  type CropperOptions,
  type ImageCroppedEvent,
  type CropperPosition,
  type ImageTransform,
  type LoadedImage,
  base64ToFile,
  resizeCanvas
} from "ngx-image-cropper";

Basic Usage

import { Component } from '@angular/core';
import { ImageCropperComponent, ImageCroppedEvent } from 'ngx-image-cropper';

@Component({
  selector: 'app-cropper',
  standalone: true,
  imports: [ImageCropperComponent],
  template: `
    <image-cropper
      [imageChangedEvent]="imageChangedEvent"
      [maintainAspectRatio]="true"
      [aspectRatio]="4 / 3"
      [resizeToWidth]="256"
      format="png"
      (imageCropped)="imageCropped($event)"
      (imageLoaded)="imageLoaded()"
      (loadImageFailed)="loadImageFailed()">
    </image-cropper>
  `
})
export class CropperComponent {
  imageChangedEvent: Event | null = null;

  onFileChange(event: Event): void {
    this.imageChangedEvent = event;
  }

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

  imageLoaded(): void {
    console.log('Image loaded successfully');
  }

  loadImageFailed(): void {
    console.log('Image load failed');
  }
}

Architecture

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

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

Capabilities

Image Cropper Component

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

@Component({
  selector: 'image-cropper',
  standalone: true
})
export class ImageCropperComponent {
  // Input properties for image sources
  @Input() imageChangedEvent?: Event | null;
  @Input() imageURL?: string;
  @Input() imageBase64?: string;
  @Input() imageFile?: File;
  @Input() imageAltText?: string;

  // Configuration options
  @Input() options?: Partial<CropperOptions>;
  @Input() output?: 'blob' | 'base64';
  @Input() format?: OutputFormat;
  @Input() autoCrop?: boolean;
  @Input() maintainAspectRatio?: boolean;
  @Input() aspectRatio?: number;
  @Input() resizeToWidth?: number;
  @Input() resizeToHeight?: number;

  // Output events
  readonly imageCropped = output<ImageCroppedEvent>();
  readonly imageLoaded = output<LoadedImage>();
  readonly cropperReady = output<Dimensions>();
  readonly loadImageFailed = output<void>();

  // Public methods
  crop(): ImageCroppedEvent | null;
  crop(output: 'base64'): ImageCroppedEvent | null;
  crop(output: 'blob'): Promise<ImageCroppedEvent> | null;
  resetCropperPosition(): void;
}

Image Cropper Component

Crop Service

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

export class CropService {
  crop(input: CropInput, output: 'blob'): Promise<ImageCroppedEvent> | null;
  crop(input: CropInput, output: 'base64'): ImageCroppedEvent | null;
  getResizeRatio(width: number, height: number, options?: ResizeOptions): number;
  getQuality(options?: { imageQuality?: number }): number;
}

Crop Service

Load Image Service

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

export class LoadImageService {
  loadImageFile(file: File, options: LoadImageOptions): Promise<LoadedImage>;
  loadImageFromURL(url: string, options: LoadImageOptions): Promise<LoadedImage>;
  loadBase64Image(imageBase64: string, options: LoadImageOptions): Promise<LoadedImage>;
  transformLoadedImage(loadedImage: Partial<LoadedImage>, options: LoadImageOptions, forceTransform?: boolean): Promise<LoadedImage>;
}

Load Image Service

Utility Functions

Helper functions for common image manipulation tasks.

function base64ToFile(base64Image: string): Blob;
function resizeCanvas(canvas: HTMLCanvasElement, width: number, height: number): void;

Utility Functions

Core Types

interface ImageCroppedEvent {
  base64?: string | null;
  blob?: Blob | null;
  objectUrl?: string | null;
  width: number;
  height: number;
  cropperPosition: CropperPosition;
  imagePosition: CropperPosition;
  offsetImagePosition?: CropperPosition;
}

interface CropperPosition {
  x1: number;
  y1: number;
  x2: number;
  y2: number;
}

interface ImageTransform {
  scale?: number;
  rotate?: number;
  flipH?: boolean;
  flipV?: boolean;
  translateH?: number;
  translateV?: number;
  translateUnit?: '%' | 'px';
}

interface Dimensions {
  width: number;
  height: number;
}

interface LoadedImage {
  original: {
    objectUrl: string;
    image: HTMLImageElement;
    size: Dimensions;
  };
  transformed: {
    objectUrl: string;
    image: HTMLImageElement;
    size: Dimensions;
  };
  exifTransform: ExifTransform;
}

interface LoadImageOptions {
  format?: OutputFormat;
  checkImageType?: boolean;
  canvasRotation?: number;
  containWithinAspectRatio?: boolean;
  aspectRatio?: number;
}

interface CropInput {
  loadedImage: LoadedImage;
  cropper: CropperPosition;
  maxSize: Dimensions;
  transform?: ImageTransform;
  options?: {
    backgroundColor?: string;
    containWithinAspectRatio?: boolean;
    maintainAspectRatio?: boolean;
    aspectRatio?: number;
    format?: OutputFormat;
    canvasRotation?: number;
    imageQuality?: number;
    resizeToWidth?: number;
    resizeToHeight?: number;
    onlyScaleDown?: boolean;
  };
}

interface ExifTransform {
  rotate: number;
  flip: boolean;
}

interface CropperOptions {
  format: OutputFormat;
  output: OutputType;
  autoCrop: boolean;
  maintainAspectRatio: boolean;
  resetCropOnAspectRatioChange: boolean;
  aspectRatio: number;
  resizeToWidth: number;
  resizeToHeight: number;
  cropperMinWidth: number;
  cropperMinHeight: number;
  cropperMaxHeight: number;
  cropperMaxWidth: number;
  cropperStaticWidth: number;
  cropperStaticHeight: number;
  canvasRotation: number;
  roundCropper: boolean;
  onlyScaleDown: boolean;
  imageQuality: number;
  backgroundColor: string | undefined;
  containWithinAspectRatio: boolean;
  hideResizeSquares: boolean;
  alignImage: 'left' | 'center';
  cropperFrameAriaLabel: string | undefined;
  checkImageType: boolean;
}

type OutputFormat = 'png' | 'jpeg' | 'bmp' | 'webp' | 'ico';
type OutputType = 'base64' | 'blob';