Home

Awesome

<p align="center"> <a href="https://CropperBlazor.github.io/"> <img src="content/cropperblazor.png?raw=true" align="center" alt="Cropper.Blazor" width="200 px"> </a> <h1 align="center"> Cropper.Blazor </h1> <p align="center"> <b>Cropper.Blazor</b> is a component that wraps around <a href="https://github.com/fengyuanchen/cropperjs"><b>Cropper.js</b></a> version 1.6.2 </p> </p>

Build and run test Deploy to GitHub Pages Deploy to NuGet coverage GitHub GitHub NuGet Badge

The most powerful image cropping tool for Blazor WebAssembly / Server, Hybrid with MAUI, MVC and other frameworks.

Cropper.Blazor is an essential component for building interactive image cropping and manipulation features in Blazor web applications. This versatile Blazor library empowers developers to integrate intuitive image cropping functionality directly into their Blazor projects, offering users a seamless and responsive image editing experience.

Demo

API

Examples

Prerequisites

Cropper.Blazor.NETSupport
-.NET 3.1Not supported
-.NET 5Not supported
1.1.x.NET 6:heavy_check_mark:
1.2.x.NET 6 & .NET 7:heavy_check_mark:
1.3.x.NET 6 & .NET 7 & .NET 8:heavy_check_mark:

Key features and aspects of the Cropper.Blazor package include

Cropper.Blazor streamlines the implementation of image cropping and editing within Blazor applications, enhancing user engagement and enabling dynamic image manipulation. Whether you are developing a Blazor-based image editor, profile picture uploader, or any other application that requires image cropping, Cropper.Blazor is a valuable package that simplifies the development process and enriches your application's capabilities.

Installation

dotnet add package Cropper.Blazor

Usage

Import Custom Element:

@using Cropper.Blazor.Components

Add the following to index.html (client-side — Blazor Webassembly, Blazor MAUI) or _Host.cshtml (server-side — Blazor Server, MVC with Blazor Server) in the head

<link href="_content/Cropper.Blazor/cropper.min.css" rel="stylesheet" />

Add the following to index.html or _Host.cshtml in the body

<script src="_content/Cropper.Blazor/cropper.min.js"></script>

Add the following to the relevant sections of Program.cs

using Cropper.Blazor.Extensions;
builder.Services.AddCropper();

In addition, you can change the path to the cropperJSInterop.min.js module if for some reason it is located outside the server root folder as follows:

builder.Services.AddCropper(new CropperJsInteropOptions()
{
    DefaultInternalPathToCropperModule = "<YourPath>/_content/Cropper.Blazor/cropperJsInterop.min.js"
})
builder.Services.AddCropper(new CropperJsInteropOptions()
{
    IsActiveGlobalPath = true,
    GlobalPathToCropperModule = "<StartUrlWithPath>/_content/Cropper.Blazor/cropperJsInterop.min.js"
})

Also for server-side (Blazor Server or MVC with Blazor Server) you need add configuration SignalR, increase MaximumReceiveMessageSize of a single incoming hub message (default is 32KB) and map SignalR to your path. However, if your images are too large, the MaximumReceiveMessageSize variable should be increased to the desired value. For example:

builder.Services.AddServerSideBlazor()
    .AddHubOptions(options =>
    {
        options.MaximumReceiveMessageSize = 32 * 1024 * 100;
    });
app.MapBlazorHub();

And then use it in Razor file (for example):

<CropperComponent
  Class="cropper-container"
  ErrorLoadImageClass="cropper-error-load"
  @ref="CropperComponent"
  OnCropStartEvent="OnCropStartEvent"
  OnCropEndEvent="OnCropEndEvent"
  OnCropEvent="OnCropEvent"
  OnZoomEvent="OnZoomEvent"
  OnCropMoveEvent="OnCropMoveEvent"
  OnReadyEvent="OnCropReadyEvent"
  OnLoadImageEvent="OnLoadImageEvent"
  Src="@Src"
  InputAttributes="@InputAttributes"
  ErrorLoadImageSrc="@_errorLoadImageSrc"
  IsErrorLoadImage="@IsErrorLoadImage"
  OnErrorLoadImageEvent="OnErrorLoadImageEvent"
  Options="Options"
  IsAvailableInitCropper="IsAvailableInitCropper">
</CropperComponent>

And then use it in *.razor.cs file

You may override Cropper JavaScript module with execution script which can replace 6 event handlers (onReady, onCropStart, onCropMove, onCropEnd, onCrop, onZoom), such as overriding the onZoom callback in JavaScript:

window.overrideOnZoomCropperEvent = (minZoomRatio, maxZoomRatio) => {
    window.cropper.onZoom = function (imageObject, event, correlationId) {
		const jSEventData = this.getJSEventData(event, correlationId);
		
		const isApplyPreventZoomMinRatio = (minZoomRatio != null) && (minZoomRatio > event.detail.ratio);
		const isApplyPreventZoomMaxRatio = (maxZoomRatio != null) && (event.detail.ratio > maxZoomRatio);

		if (isApplyPreventZoomMinRatio || isApplyPreventZoomMaxRatio) {
            event.preventDefault();
        }
        else {
            imageObject.invokeMethodAsync('CropperIsZoomed', jSEventData);
        }
    };
};

Analysis of the signature onReady, onCropStart, onCropMove, onCropEnd, onCrop, onZoom event handlers:

imageObject

Reference to base cropper component.

event

Represent Cropper Event.

correlationId

A Correlation ID is a unique identifier that is added to the very first interaction(incoming request) to identify the context and is passed to all components that are involved in the transaction flow.

Definitely need to tell these rules in Blazor:

await JSRuntime!.InvokeVoidAsync("window.overrideCropperJsInteropModule", MinZoomRatio, MaxZoomRatio);

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b feature/<my-new-feature>
  3. Commit your changes: git commit -m 'Add some feature'
  4. Push to the branch: git push origin feature/<my-new-feature>
  5. Submit a pull request :D