Installation
Check the Installation page for instructions on setting up the library before using cropper component.
Simple Usage
To start using the cropper component, you must specify the path to the image
with which you will work in the Src
property.
You also need to specify the cropper settings using the Options
property,
which can be left as default, as in the example below.

<CropperComponent Class="big-img" Src="images/Rivne.jpg" Options="new Blazor.Models.Options()" /> @* Make sure the size of the image fits perfectly into the container *@ <style> .big-img { max-height: 500px; /* This rule is very important, please don't ignore this */ max-width: 100%; } </style>
Cropper sizing
The size of the cropper inherits from the size of the image's parent element (wrapper),
so be sure to wrap the image with a visible block element.

<div class="img-container"> <CropperComponent Src="cropperblazor.png" Options="new Blazor.Models.Options()" /> </div> <style> .img-container { max-height: 300px; width: 100%; } </style>
Image loading error
You can use the OnErrorLoadImageEvent
event and the
ErrorLoadImageSrc
prop to notify the user of an error loading a photo in Cropper.
For example, the Src
property contains an incorrect path to the photo,
so the cropper will not be created during initialization, and the image will be replaced with
what was specified in the ErrorLoadImageSrc
property.
You can add css styles to the image using the ErrorLoadImageClass
property,
as is done with the second cropper in the example:
<CropperComponent Src="incorrect-image-link" ErrorLoadImageSrc="images/error300px.png" IsErrorLoadImage="" OnErrorLoadImageEvent="OnErrorLoadImageEvent" Options="new Blazor.Models.Options()" /> <CropperComponent Src="incorrect-image-link" ErrorLoadImageSrc="images/error300px.png" ErrorLoadImageClass="error-image" IsErrorLoadImage="" OnErrorLoadImageEvent="OnErrorLoadImageEvent" Options="new Blazor.Models.Options()" />
@code { private bool IsErrorLoadImage { get; set; } = false; public void OnErrorLoadImageEvent(ErrorEventArgs errorEventArgs) { // You can use 'ErrorLoadImageContent' instead of 'ErrorLoadImageSrc', 'ErrorLoadImageClass' // parameters in cropper component to set up custom error image content IsErrorLoadImage = true; StateHasChanged(); } } <style> .error-image { filter: grayscale(100%); } </style>
Load cross-origin image
A cross origin image with a crossorigin attribute and an available Access-Control-Allow-Origin response header can be cropped by Cropper.Blazor.
If you try to start cropper on a cross-origin image, please make sure that your browser supports
HTML5 CORS settings attributes,
and your image server supports the Access-Control-Allow-Origin option (see the HTTP access control (CORS)).
If your image isn't be a cross-origin, set the CheckCrossOrigin
in the Options
property to false
.

@using Cropper.Blazor.Models <div class="img-container"> <CropperComponent Src="cropperblazor.png" Options="options" InputAttributes="InputAttributes" /> </div> <style> .img-container { max-height: 300px; width: 100%; } </style>
@code { private Options options; public Dictionary<string, object> InputAttributes { get; set; } = new Dictionary<string, object> { { "crossorigin", "anonymous" } // Another possible values: "use-credentials" or "" (the same as "anonymous"). An invalid keyword and an empty string will be handled as the anonymous keyword. For more information see official https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin documentation }; protected override void OnInitialized() { options = new Options { }; } }
Canvas Cropper
You can use the
CropperComponentType.Canvas
mode to work directly with the HTML <canvas>
element instead of an <img>
element.
This mode is ideal for scenarios like drawing apps, painting utilities, or image editors where you need full programmatic control over the canvas.
Since
CropperComponentType.Canvas
does not use the Src
property, you must manually draw content to the canvas — typically via JavaScript interop or a graphics library
before calling InitCropper()
.
Since this mode doesn't use an element, image-related events like
OnLoadImage
and OnErrorLoadImage
won't be triggered.
Instead, you should handle the cropper's lifecycle and error management manually using the component's available API methods.
@using Cropper.Blazor.Models <div class="cropper-canvas-container"> <CropperComponent @ref="cropperComponent" IsErrorLoadImage="" ErrorLoadImageSrc="images/error300px.png" ErrorLoadImageClass="error-image" CropperComponentType="CropperComponentType.Canvas" InputAttributes="" Options="options" /> </div> @if (!IsErrorLoadImage) { <div class="button" @onclick="SetError"> Set Error </div> } <style> .cropper-canvas-container { max-height: 300px; width: 100%; /* These styles below are just needed for a nice button and don't related with cropper component */ display: flex; justify-content: center; align-items: center; } .error-image { filter: grayscale(100%); } /* These styles are just needed for a nice button and don't related with cropper component */ .button { display: inline-block; padding: 10px 20px; background-color: #007bff; color: #fff; border: none; border-radius: 5px; text-align: center; text-decoration: none; font-size: 16px; cursor: pointer; } </style>
@code { [Inject] private IJSRuntime? JSRuntime { get; set; } private CropperComponent? cropperComponent = null!; private Options options; private bool IsErrorLoadImage { get; set; } = false; public Dictionary<string, object> InputAttributes { get; set; } = new Dictionary<string, object> { { "id", "canvas-cropper" } }; protected override void OnInitialized() { options = new Options { }; } protected override async Task OnAfterRenderAsync(bool firstRender) { if (firstRender) { // When using CropperComponentType.Canvas, the canvas element is used directly // instead of an <img> tag. This requires manually drawing or uploading an image // into the <canvas> element via JavaScript or library. Error handling (e.g., for failed image // loading) is also your responsibility in this case. // This approach is ideal when you’re building a drawing, painting, or image editing // tool where you need full control over the canvas content. ElementReference? canvasElementReference = cropperComponent!.GetCropperElementReference(); // Example: Fill the canvas with random colors using JavaScript await JSRuntime!.InvokeVoidAsync( "fillCanvasWithRandomColors", canvasElementReference); // Initialize the cropper component after the canvas is ready cropperComponent.InitCropper(); } await base.OnAfterRenderAsync(firstRender); } public void SetError() { // You can use 'ErrorLoadImageContent' instead of 'ErrorLoadImageSrc', 'ErrorLoadImageClass' // parameters in cropper component to set up custom error image content IsErrorLoadImage = true; cropperComponent!.Destroy(); } }