Angular Ionic Image Cropper

A lightweight Angular library for image cropping with Ionic integration. This library provides a simple and customizable image cropper component that works seamlessly with Ionic applications.

Features

• 🖼️ Image Cropping: Crop images with customizable aspect ratios
• 📱 Ionic Integration: Built specifically for Ionic applications
• 📷 Camera Support: Optional camera integration via Capacitor
• 📦 Lightweight: Minimal dependencies
• 🔧 TypeScript: Full TypeScript support

Installation

npm install @bitforgehq/angular-ionic-image-cropper

Import Global Styles (Recommended)

To ensure proper styling, especially for iOS builds, import the global styles in your application:

In your main styles file (e.g., src/styles.scss):

@use '@bitforgehq/angular-ionic-image-cropper/index.scss';

Or in your angular.json:

{
  "styles": [
    "src/styles.scss",
    "node_modules/@bitforgehq/angular-ionic-image-cropper/index.scss"
  ]
}

Note: The styles are automatically included when you import the library, but for iOS builds, it's recommended to explicitly import the styles to ensure proper functionality. This library includes iOS-specific fixes for common rendering issues.

Dependencies

This library requires the following peer dependencies:

{
  "@angular/common": "^20.1.0",
  "@angular/core": "^20.1.0",
  "@ionic/angular": "^8.0.0"
}

For camera functionality, install the optional dependency:

npm install @capacitor/camera

Usage

1. Import the Module

In your Angular module or standalone component:

import { ImageCropperComponent, ImageCropperService } from '@bitforgehq/angular-ionic-image-cropper';

@Component({
  // ... your component config
  imports: [ImageCropperComponent]
})
export class YourComponent {
  private imageCropperService = inject(ImageCropperService);
}

2. Basic Usage

Using the Service (Recommended)

import { ImageCropperService, ImageCropperConfig } from '@bitforgehq/angular-ionic-image-cropper';

export class YourComponent {
  private imageCropperService = inject(ImageCropperService);

  async cropImage() {
    try {
      // Open cropper with an image URL
      const croppedBlob = await this.imageCropperService.openCropper(
        'path/to/your/image.jpg',
        {
          aspectRatio: 16 / 9,   // optional, defaults to 16/9
          cancelText: 'Cancel',  // optional, defaults to 'Cancel'
          doneText: 'Done'       // optional, defaults to 'Done'
        }
      );
      
      console.log('Cropped image:', croppedBlob);
    } catch (error) {
      console.error('Crop cancelled or failed:', error);
    }
  }

  async takeAndCropPhoto() {
    try {
      // Take a photo and crop it
      const croppedBlob = await this.imageCropperService.takeAndCropPhoto({
        aspectRatio: 1,                // square aspect ratio
        cancelText: 'Cancel',          // 'cancel' button text
        doneText: 'Done',              // 'confirm' button text
        quality: 0.8,                  // 80% quality
        outputFormat: 'image/png'      // PNG format
      });
      
      console.log('Cropped photo:', croppedBlob);
    } catch (error) {
      console.error('Photo capture or crop failed:', error);
    }
  }
}

API Reference

ImageCropperService

Configuration Interface

interface ImageCropperConfig {
  /**
   * Text to display on the cancel button
   * @default 'Cancel'
   */
  cancelText?: string;
  
  /**
   * Text to display on the done/confirm button
   * @default 'Done'
   */
  doneText?: string;
  
  /**
   * Aspect ratio for the crop area (width / height)
   * Common values: 1 (square), 16/9 (widescreen), 4/3 (standard)
   * @default 16/9
   */
  aspectRatio?: number;
  
  /**
   * Quality of the output image (0.1 to 1.0)
   * @default 0.9
   */
  quality?: number;
  
  /**
   * Output format for the cropped image
   * @default 'image/jpeg'
   */
  outputFormat?: 'image/jpeg' | 'image/png' | 'image/webp';
}

Methods

• openCropper(imagePath: string, config?: ImageCropperConfig): Promise<Blob>

  • Opens the cropper modal with the specified image
  • Returns a Promise that resolves to the cropped image as a Blob
  • Throws an error if the crop is cancelled

• takeAndCropPhoto(config?: ImageCropperConfig): Promise<Blob>

  • Opens the camera, takes a photo, then opens the cropper
  • Returns a Promise that resolves to the cropped image as a Blob
  • Requires @capacitor/camera to be installed

Browser Support

This library supports all modern browsers that support:

• ES2015+ features
• Canvas API
• File API

Troubleshooting

iOS Build Issues

If you experience rendering issues on iOS builds, ensure you have imported the global styles:

// In your global styles file
@use '@bitforgehq/angular-ionic-image-cropper/index.scss';

Cropper Not Displaying Properly

If the cropper modal doesn't display correctly, check that:

1. The cropper CSS is properly imported
2. Your app has proper viewport meta tags
3. The modal container has sufficient z-index

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.