ngx-image-cropper

What is ngx-image-cropper?

The ngx-image-cropper is an Angular library that provides a highly customizable image cropping tool. It allows users to crop images in various shapes and sizes, and offers a range of features to enhance the image cropping experience.

What are ngx-image-cropper's main functionalities?

Basic Image Cropping

This feature allows users to crop images while maintaining a specific aspect ratio. The cropped image is emitted in the specified format (e.g., PNG).

<image-cropper [imageChangedEvent]="imageChangedEvent" [maintainAspectRatio]="true" [aspectRatio]="4 / 3" format="png" (imageCropped)="imageCropped($event)"></image-cropper>

Free Aspect Ratio Cropping

This feature allows users to crop images without maintaining a fixed aspect ratio, providing more flexibility in selecting the crop area.

<image-cropper [imageChangedEvent]="imageChangedEvent" [maintainAspectRatio]="false" format="jpeg" (imageCropped)="imageCropped($event)"></image-cropper>

Round Cropping

This feature allows users to crop images in a circular shape, which is useful for profile pictures and other round image requirements.

<image-cropper [imageChangedEvent]="imageChangedEvent" [maintainAspectRatio]="true" [aspectRatio]="1 / 1" [roundCropper]="true" format="png" (imageCropped)="imageCropped($event)"></image-cropper>

Image Rotation

This feature allows users to rotate the image before cropping, ensuring the image is properly oriented.

<image-cropper [imageChangedEvent]="imageChangedEvent" [maintainAspectRatio]="true" [aspectRatio]="4 / 3" format="png" (imageCropped)="imageCropped($event)" (imageLoaded)="imageLoaded()" (cropperReady)="cropperReady()" (loadImageFailed)="loadImageFailed()"></image-cropper>

Other packages similar to ngx-image-cropper

cropperjs

Cropper.js is a JavaScript image cropping library that provides a rich set of features for cropping images. It is highly customizable and can be used with various frameworks, including Angular. Compared to ngx-image-cropper, Cropper.js offers more advanced features and greater flexibility but requires more setup and integration effort.

react-image-crop

React Image Crop is a library specifically designed for React applications. It provides a simple and easy-to-use interface for cropping images. While it offers similar functionalities to ngx-image-cropper, it is tailored for React rather than Angular, making it a better choice for React developers.

vue-cropper

Vue Cropper is a Vue.js component for image cropping. It offers a range of features similar to ngx-image-cropper but is designed for use with Vue.js. It provides a seamless integration with Vue applications and is a good alternative for developers working with the Vue framework.

README

Image cropper for Angular

StackBlitz

Installation

npm install ngx-image-cropper --save

Upgrade instructions

For a list of breaking changes and update instructions, go to releases. Only Angular 13+ is supported since image cropper version 6.0.0.

Example usage

Add the ImageCropperModule to the imports of the module which will be using the Image Cropper.

import { NgModule } from '@angular/core';
import { ImageCropperModule } from 'ngx-image-cropper';

@NgModule({
    imports: [
        ...
        ImageCropperModule
    ],
    declarations: [
        ...
    ],
    exports: [
        ...
    ],
    providers: [
        ...
    ]
})
export class YourModule {
}

Add the element to your HTML:

<input type="file" (change)="fileChangeEvent($event)" />

<image-cropper
    [imageChangedEvent]="imageChangedEvent"
    [maintainAspectRatio]="true"
    [aspectRatio]="4 / 3"
    format="png"
    (imageCropped)="imageCropped($event)"
    (imageLoaded)="imageLoaded($event)"
    (cropperReady)="cropperReady()"
    (loadImageFailed)="loadImageFailed()"
></image-cropper>

<img [src]="croppedImage" />

And add this to your ts file:

import { ImageCroppedEvent, LoadedImage } from 'ngx-image-cropper';
import { DomSanitizer } from '@angular/platform-browser';

export class YourComponent {
    imageChangedEvent: any = '';
    croppedImage: any = '';
    
    constructor(
      private sanitizer: DomSanitizer
    ) {
    }

    fileChangeEvent(event: any): void {
        this.imageChangedEvent = event;
    }
    imageCropped(event: ImageCroppedEvent) {
      this.croppedImage = this.sanitizer.bypassSecurityTrustUrl(event.objectUrl);
      // event.blob can be used to upload the cropped image
    }
    imageLoaded(image: LoadedImage) {
        // show cropper
    }
    cropperReady() {
        // cropper ready
    }
    loadImageFailed() {
        // show message
    }
}

When you choose a file from the file input, it will trigger fileChangeEvent. That event is then passed to the image cropper through imageChangedEvent which will load the image into the cropper. Everytime you release the mouse, the imageCropped event will be triggered with the cropped image as a Base64 string in its payload.

API

All inputs are optional. Either the imageChangedEvent, imageBase64 or imageFile should be set to load an image into the cropper.

Inputs

Name	Type	Default	Description
imageChangedEvent	FileEvent		The change event from your file input (set to null to reset the cropper)
imageFile	Blob(File)		The file you want to change (set to null to reset the cropper)
imageBase64	string		If you don't want to use a file input, you can set a base64 image directly and it will be loaded into the cropper
imageURL	string		If you don't want to use a file input or a base64 you can set an URL to get the image from. If requesting an image from a different domain make sure Cross-Origin Resource Sharing (CORS) is allowed or the image will fail to load.
imageAltText	string		Alternative text for uploaded image for accessibility compliance.
cropperFrameAriaLabel	string	'Crop photo'	Aria-label text for the focusable cropper frame element.
format	string	png	Output format (png, jpeg, webp, bmp, ico) (not all browsers support all types, png is always supported, others are optional)
output	string	blob	Output type (blob or base64) (blob is the most performant)
aspectRatio	number	1 / 1	The width / height ratio (e.g. 1 / 1 for a square, 4 / 3, 16 / 9 ...)
maintainAspectRatio	boolean	true	Keep width and height of cropped image equal according to the aspectRatio
containWithinAspectRatio	boolean	false	When set to true, padding will be added around the image to make it fit to the aspect ratio
resizeToWidth	number	0 (disabled)	Cropped image will be resized to at most this width (in px)
resizeToHeight	number	0 (disabled)	Cropped image will be resized to at most this height (in px)
cropperStaticWidth	number	0 (disabled)	Set Cropper Width and disable resize (in px)
cropperStaticHeight	number	0 (disabled)	Set Cropper Height and disable resize (in px)
cropperMinWidth	number	0 (disabled)	The cropper cannot be made smaller than this number of pixels in width (relative to original image's size) (in px)
cropperMinHeight	number	0 (disabled)	The cropper cannot be made smaller than this number of pixels in height (relative to original image's size) (in px) (will be ignored if maintainAspectRatio is set)
cropperMaxWidth	number	0 (disabled)	The cropper cannot be made bigger than this number of pixels in width (in px)
cropperMaxHeight	number	0 (disabled)	The cropper cannot be made bigger than this number of pixels in height (in px)
initialStepSize	number	3 (px)	The initial step size in pixels when moving the cropper using the keyboard. Step size can then be changed by using the numpad when the cropper is focused
onlyScaleDown	boolean	false	When the resizeToWidth or resizeToHeight is set, enabling this option will make sure smaller images are not scaled up
cropper	CropperPosition		To be able to overwrite the cropper coordinates, you can use this input. Create a new object of type CropperPosition and assign it to this input. Make sure to create a new object each time you wish to overwrite the cropper's position and wait for the cropperReady event to have fired.
roundCropper	boolean	false	Set this to true for a round cropper. Resulting image will still be square, use border-radius: 100% on resulting image to show it as round.
imageQuality	number	92	This only applies when using jpeg or webp as output format. Entering a number between 0 and 100 will determine the quality of the output image.
autoCrop	boolean	true	When set to true, the cropper will emit an image each time the position or size of the cropper is changed. When set to false, you can call the crop method yourself (use @ViewChild to get access to the croppers methods).
alignImage	'left' or 'center'	'center'	Use this to align the image in the cropper either to the left or center.
backgroundColor	string		Use this to set a backgroundColor, this is useful if you upload an image of a format with transparent colors and convert it to 'jpeg' or 'bmp'. The transparent pixels will then become the set color or the default value. Enter any string representing a CSS color (https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
hideResizeSquares	boolean	false	Disables the resize-squares at the border of the cropper. This is mostly useful for Touch Devices where you can change the Size of the Cropper via Pinch-To-Zoom
disabled	boolean	false	Disables the component and prevents changing the cropper position
canvasRotation	number	0	Rotate the canvas (1 = 90deg, 2 = 180deg...)
transform	ImageTransform	{}	Flip, rotate and scale image. (if allowMoveImage is enabled, make sure to use 2-way data binding [(transform)]="transform".
allowMoveImage	boolean	false	Allow background image to be moved. When enabled and using the transform input, make sure to use 2-way data binding for the transform input ([(transform)]="transform").
hidden	boolean	false	Set to true to hide image cropper

CSS Variables

Name	Type	Default	Description
--cropper-outline-color	string	rgba(255,255,255,0.3)	The background color you see around the cropper
--cropper-overlay-color	string	rgba(255,255,255)	The background color you see around the image

Outputs

Name	Type	Description
imageCropped	ImageCroppedEvent	Emits an ImageCroppedEvent each time the image is cropped
imageLoaded	LoadedImage	Emits the LoadedImage when it was loaded into the cropper
cropperReady	Dimensions	Emits when the cropper is ready to be interacted. The Dimensions object that is returned contains the displayed image size
startCropImage	void	Emits when the component started cropping the image
loadImageFailed	void	Emits when a wrong file type was selected (only png, gif and jpg are allowed)

Methods

To gain access to the image cropper's methods use @ViewChild(ImageCropperComponent) imageCropper: ImageCropperComponent;

Name	Returns	Description
crop(output?: 'blob' | 'base64')	Promise or ImageCroppedEvent	Crops the source image to the current cropper position. Be sure to set autoCrop to false if you only wish to use this function directly. When output is set to blob, a Promise will be returned.

Interfaces

CropperPosition

Property	Type	Description
x1	number	X position of first coordinate (in px)
y1	number	Y position of first coordinate (in px)
x2	number	X position of second coordinate (in px)
y2	number	Y position of second coordinate (in px)

ImageTransform

Property	Type	Description
scale	number	Scale image (1=normal, 2=2x zoom...)
rotate	number	Rotation in degrees
flipH	boolean	Flipped horizontally
flipV	boolean	Flipped vertically
translateH	number	Move horizontally (in %)
translateV	number	Moved vertically (in %)
translateUnit	number	The unit used for the translate (% or px) (default = %)

ImageCroppedEvent

Property	Type	Description
blob	Blob	Blob of the cropped image (only if output="blob")
objectUrl	string	Object url pointing to the generated blob (only if output="blob")
base64	string	Base64 string of the cropped image (only if output="base64")
width	number	Width of the cropped image
height	number	Height of the cropped image
cropperPosition	CropperPosition	Position of the cropper when it was cropped relative to the displayed image size
imagePosition	CropperPosition	Position of the cropper when it was cropped relative to the original image size
offsetImagePosition	CropperPosition	Position of the cropper when it was cropped relative to the original image size without padding when containWithinAspectRatio is true

LoadedImage

Property	Type	Description
original.objectUrl	string	Object url pointing to the original image
original.image	HTMLImageElement	HTMLImageElement of the original image
original.size	Dimension	Width and height of the original image
transformed.objectUrl	string	Object url pointing to the transformed image
transformed.image	HTMLImageElement	HTMLImageElement of the transformed image
transformed.size	Dimension	Width and height of the transformed image
exifTransform	ExifTransform	Exif transformations read from original image