@one-crop-image/angular

A powerful, accessible image-cropping component for Angular — rotation, mirroring, zoom, filters, aspect-ratio presets, undo/redo history, and drag-and-drop upload, with export to PNG, JPEG, or WebP.

Features

• ✂️ Precise cropping — draggable, resizable crop region with rectangle or circle shape
• 🔄 Rotate & mirror — 90° steps or free rotation at any angle, horizontal/vertical flip
• 🔍 Smooth zoom — configurable range and step, buttons and mouse-wheel support
• 📐 Aspect-ratio presets — 1:1, 4:3, 16:9 and more, extensible with custom presets
• 🎨 Live filters — brightness, contrast, and saturation rendered in real time
• ↩️ Undo / redo — full history of every transform, exposed through events
• 📏 Composition guides — rule of thirds, golden ratio, or diagonal overlays
• 📁 Drag & drop — drop a file onto the stage or use the built-in file picker
• 📦 Flexible export — PNG / JPEG / WebP as File, Blob, base64, or canvas, with size limits
• ♿ Accessible — focus management via Angular CDK and keyboard operability
• 🧩 Standalone-first — works as a standalone component or via OneImageCropModule

Installation

npm install @one-crop-image/angular

Peer dependencies: @angular/core, @angular/common, @angular/forms, @angular/cdk (>= 19) and rxjs.

npm install @angular/cdk

Quick start

Standalone component (recommended)

import { Component } from '@angular/core';
import { OneImageCropComponent } from '@one-crop-image/angular';

@Component({
  selector: 'app-avatar-upload',
  standalone: true,
  imports: [OneImageCropComponent],
  template: `
    <one-image-crop
      [enableRotate]="true"
      [enableZoom]="true"
      [outputFormat]="'image/jpeg'"
      [outputQuality]="0.9"
      (onImageCroppedAction)="onCropped($event)">
    </one-image-crop>
  `
})
export class AvatarUploadComponent {
  onCropped(file: File): void {
    // Upload or preview the cropped file
  }
}

NgModule with global defaults

import { NgModule } from '@angular/core';
import { OneImageCropModule } from '@one-crop-image/angular';

@NgModule({
  imports: [
    OneImageCropModule.forRoot({
      outputFormat: 'image/jpeg',
      outputQuality: 0.9,
      guidelineType: 'rule-of-thirds'
    })
  ]
})
export class AppModule {}

Bulk configuration

Every option can also be passed at once through the config input; individual inputs take precedence.

<one-image-crop
  [config]="{
    enableRotate: true,
    enableFilters: true,
    enableHistory: true,
    cropShape: 'circle',
    outputFormat: 'image/webp',
    maxOutputWidth: 1024,
    maxOutputHeight: 1024
  }"
  (onImageCroppedAction)="onCropped($event)"
  (onHistoryChange)="onHistoryChange($event)">
</one-image-crop>

API

Inputs

| Input | Type | Default | Description | | --- | --- | --- | --- | | config | Partial<ImageCropConfig> | {} | Bulk configuration object; individual inputs override it. | | imageUrl | string \| null | null | Load an image from a URL instead of the file picker. | | enableRotate | boolean | true | Show 90° rotation controls. | | enableFreeRotation | boolean | true | Allow rotation by arbitrary angles. | | enableMirror | boolean | true | Show horizontal / vertical flip controls. | | enableZoom | boolean | true | Allow zooming with buttons and mouse wheel. | | enableFilters | boolean | false | Show brightness, contrast, and saturation filters. | | enablePresets | boolean | false | Show aspect-ratio preset buttons. | | enableHistory | boolean | true | Enable undo / redo history. | | enableShortcuts | boolean | false | Enable keyboard shortcuts. | | enableAutoCrop | boolean | false | Detect and suggest a crop region automatically. | | disableDragDrop | boolean | false | Turn off drag-and-drop file upload. | | disable | boolean | false | Disable the whole component. | | showGuidelines | boolean | true | Overlay composition guidelines on the crop area. | | guidelineType | 'rule-of-thirds' \| 'golden-ratio' \| 'diagonal' | 'rule-of-thirds' | Which guideline pattern to draw. | | cropShape | 'rectangle' \| 'circle' | 'rectangle' | Shape of the crop selection. | | minZoom / maxZoom / zoomStep | number | 1 / 5 / 0.08 | Zoom range and step size. | | outputFormat | 'image/png' \| 'image/jpeg' \| 'image/webp' | 'image/png' | MIME type of the exported image. | | outputQuality | number | 0.92 | Encoder quality for JPEG / WebP (0–1). | | outputWidth / outputHeight | number | — | Force exact output dimensions. | | maxOutputWidth / maxOutputHeight | number | — | Cap output dimensions while keeping aspect ratio. | | maxBytes | number | 1048576 | Maximum exported file size in bytes. | | emitType | 'file' \| 'base64' \| 'both' | 'file' | Which output events are emitted after cropping. |

Outputs

| Output | Payload | Description | | --- | --- | --- | | onImageCroppedAction | File | Fires with the cropped image as a File. | | onImageCroppedBase64 | string | Fires with the cropped image as a base64 data URL. | | onImageCroppedBlob | Blob | Fires with the cropped image as a Blob. | | onImageCroppedCanvas | HTMLCanvasElement | Fires with the canvas holding the cropped image. | | onHistoryChange | { canUndo: boolean; canRedo: boolean } | Fires when undo / redo availability changes. | | onFiltersChange | FilterState | Fires when filter values change. | | onMultipleCropsExport | { crops: File[]; metadata: any[] } | Fires when multiple crop regions are exported. |

Services & types

Beyond the component, the package exports the underlying services (ExportService, ImageTransformService, HistoryService, CropCalculationService, and more), the CropEventBus, and all TypeScript interfaces (ImageCropConfig, CropRect, ImageState, …) for advanced integrations.

Compatibility

| @one-crop-image/angular | Angular | | --- | --- | | 1.x | >= 19 |

Contributing

Issues and pull requests are welcome at the GitHub repository.

License

MIT © Phanith Nhoem