Basic usage

Here are examples of basic usage of the cropper component.

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.

Note: With the release of version 1.2.7 of the Cropper.Blazor NuGet package, сropper's default settings will be set automatically, so you do not need to define them when declaring a component.

<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.

Note: If you are using cropper in a modal, you should initialize the cropper after the modal is shown completely. Otherwise, you will not get the correct cropper.

<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="@IsErrorLoadImage" OnErrorLoadImageEvent="OnErrorLoadImageEvent"
                  Options="new Blazor.Models.Options()" />

<CropperComponent Src="incorrect-image-link" ErrorLoadImageSrc="images/error300px.png"
                  ErrorLoadImageClass="error-image" IsErrorLoadImage="@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.

Set Error
@using Cropper.Blazor.Models

<div class="cropper-canvas-container">
    <CropperComponent @ref="cropperComponent"
                      IsErrorLoadImage="@IsErrorLoadImage"
                      ErrorLoadImageSrc="images/error300px.png"
                      ErrorLoadImageClass="error-image"
                      CropperComponentType="CropperComponentType.Canvas"
                      InputAttributes="@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();
    }
}
An unhandled error has occurred. Reload 🗙