Added in v1.2

Blazorise Cropper component

A component used to crop images.

When building an application, best practice requires reducing an image's surrounding noise and directing a user's attention to a specific part of the image. Image cropping is a method for manipulating images to remove any unwanted elements. By changing the aspect ratio or orientation, we can draw viewers' eyes to the photograph's primary subject and improve the overall composition. This applies to profile pictures or uploading images with specific dimensions.

The Cropper component handles all of that. You can upload an image and then select part of it, rotate, scale, and crop it. You can also add a preview by placing a CropperViewer anywhere on a page, and it will automatically synchronize with the latest selection.

To use the Cropper component, install the Blazorise.Cropper package first.

Installation

NuGet

Install extension from NuGet.

Install-Package Blazorise.Cropper

Imports

In your main _Imports.razor add:

@using Blazorise.Cropper

Message Size

This step is recommended for Blazor Server only. In a default Blazor Server project template, the SignalR settings might be too small for some components like Cropper. To make it work, you should increase the MaximumReceiveMessageSize in your projects Startup.cs.

.AddHubOptions(o =>
{
    o.MaximumReceiveMessageSize = 1024 * 1024 * 100;
})

Examples

Basic

The image cropper is straightforward. You need to define a Source parameter and a reference.

Image Cropper

<Row>
    <Column>
        <FieldLabel>
            Image Cropper
        </FieldLabel>
        <FieldBody>
            <Cropper @ref="cropper" Source="img/gallery/6.jpg" SelectionChanged="@OnSelectionChanged" Style="aspect-ratio: 16 / 9; height: 100%;" />
        </FieldBody>
    </Column>
    <Column>
        <Div Margin="Margin.Is2.FromBottom">
            <Button Color="Color.Primary" Clicked="@GetCroppedImage" Disabled="@cropButtonDisabled">Get Cropped Image</Button>
            <Button Color="Color.Secondary" Clicked="@ResetSelection" Disabled="@cropButtonDisabled">Reset Selection</Button>
        </Div>
        <Image Source="@result" Border="Border.Is1" Style="width: 250px; height: 250px;" />
    </Column>
</Row>

@code {
    private Cropper cropper;
    private string result;
    private bool cropButtonDisabled = true;

    private Task OnSelectionChanged( CropperSelectionChangedEventArgs eventArgs )
    {
        if ( eventArgs.Width != 0 )
        {
            cropButtonDisabled = false;

            return InvokeAsync( StateHasChanged );
        }

        return Task.CompletedTask;
    }

    private async Task GetCroppedImage()
    {
        result = await cropper.CropAsBase64ImageAsync( new() { Width = 250, Height = 250 } );
    }

    private async Task ResetSelection()
    {
        cropButtonDisabled = true;

        await cropper.ResetSelection();
    }
}

Viewer

To add preview support, use a <CropperViewer> component. Once added you need to connect it to a <Cropper> by assigning the CropperState parameter. This parameter is used as a synchronization context between the cropper and a viewer.

Image Cropper

Preview

<Row>
    <Column>
        <FieldLabel>
            Image Cropper
        </FieldLabel>
        <FieldBody>
            <Cropper Source="img/gallery/3.jpg" CropperState="@cropperState" />
        </FieldBody>
    </Column>
    <Column>
        <FieldLabel>
            Preview
        </FieldLabel>
        <FieldBody>
            <CropperViewer CropperState="@cropperState" Margin="Margin.Is2.FromBottom" Style="width: 150px; height: 150px;" />
            <CropperViewer CropperState="@cropperState" Margin="Margin.Is2.FromBottom" Style="width: 100px; height: 100px;" />
            <CropperViewer CropperState="@cropperState" Margin="Margin.Is2.FromBottom" Style="width: 50px; height: 50px;" />
        </FieldBody>
    </Column>
</Row>

@code {
    private CropperState cropperState = new();
}

API

Parameters

Cropper

Parameter	Description	Type	Default
`Alt`	The alt text of the image.	`string`
`CropperState`	Provides the shared state and synchronization context between the cropper and cropper viewer.	`CropperState`	`null`
`CrossOrigin`	The cross-origin attribute of the image.	`string`
`Enabled`	Enables or disables cropper interactions.	`bool`	`true`
`GridOptions`	Defines the grid overlay drawn inside the crop selection.	`CropperGridOptions`	`new CropperGridOptions()`
`ImageOptions`	Controls which image transform operations are available.	`CropperImageOptions`	`new CropperImageOptions()`
`SelectionOptions`	Defines the behavior and initial shape of the crop selection.	`CropperSelectionOptions`	`new CropperSelectionOptions()`
`ShowBackground`	Shows the grid background behind the cropper.	`bool`	`true`
`Source`	The source of the image.	`string`

CropperViewer

Parameter	Description	Type	Default
`CropperState`	Provides the shared state and synchronization context between the cropper and cropper viewer.	`CropperState`	`null`

CropperCropOptions

Parameter	Description	Type	Default
`Height`	Output canvas height in pixels.	`int`	`0`
`ImageQuality`	Compression quality for lossy formats, from `0` to `1`. Remarks A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.	`double?`	`1d`
`ImageType`	MIME type for the encoded cropped image. Defaults to `image/png`.	`string`	`"image/png"`
`Width`	Output canvas width in pixels.	`int`	`0`

CropperImageOptions

Parameter	Description	Type	Default
`Rotatable`	Rotation commands can change the image angle.	`bool`	`true`
`Scalable`	Scale commands can resize the image on the X or Y axis.	`bool`	`true`
`Skewable`	Skew commands can slant the image horizontally or vertically.	`bool`	`false`
`Translatable`	Move commands can reposition the image within the cropper.	`bool`	`true`

CropperSelectionOptions

Parameter	Description	Type	Default
`AspectRatio`	Fixed ratio maintained while resizing the selection.	`CropperAspectRatio`	`CropperAspectRatio.Is1x1`
`InitialAspectRatio`	Ratio used for the selection created during initialization.	`CropperAspectRatio`	`CropperAspectRatio.Is1x1`
`InitialCoverage`	Fraction of the image covered by the initial selection, from `0` to `1`.	`double?`	`null`
`Keyboard`	Keyboard input can move or resize the active selection.	`bool`	`true`
`Movable`	The selection can be dragged to a new position.	`bool`	`true`
`Outlined`	The selection renders with a visible outline.	`bool`	`true`
`Resizable`	Selection edges and handles can change its size.	`bool`	`true`
`Zoomable`	Mouse wheel or gesture zoom can be applied from the selection.	`bool`	`true`

CropperGridOptions

Parameter	Description	Type	Default
`Bordered`	The grid renders border lines around its cells.	`bool`	`true`
`Columns`	Number of vertical grid divisions.	`int`	`3`
`Covered`	The grid fills the full selection area.	`bool`	`true`
`Rows`	Number of horizontal grid divisions.	`int`	`3`

Events

Cropper

Event	Description	Type
`CropEnded`	This event fires when the canvas (image wrapper) or the crop box stops changing.	`Func<Task>`
`CropMoved`	This event fires when the canvas (image wrapper) or the crop box is changing.	`Func<Task>`
`Cropped`	This event fires when the canvas (image wrapper) or the crop box changes.	`Func<CropperCroppedEventArgs, Task>`
`CropStarted`	This event fires when the canvas (image wrapper) or the crop box starts to change.	`Func<Task>`
`ImageLoadingFailed`	This event fires when the image cannot be loaded. Usually because of 404 or Source being null. Returns an error message as a parameter.	`Func<string, Task>`
`ImageReady`	This event fires when the image is ready / loaded.	`Func<Task>`
`SelectionChanged`	The event is fired when the position or size of the selection is going to change.	`Func<CropperSelectionChangedEventArgs, Task>`
`Zoomed`	This event fires when a cropper instance starts to zoom in or zoom out its canvas (image wrapper).	`Func<CropperZoomedEventArgs, Task>`

Methods

Cropper

Method	Description	Return	Parameters
`Center`	Center the image.	`ValueTask`	`string size`
`CropAsBase64ImageAsync`	Get the cropped image as Base64 image.	`ValueTask<string>`	`CropperCropOptions options`
`MoveTo`	Moves the image to a specific position.	`ValueTask`	`int x, int y`
`Move`	Moves the image.	`ValueTask`	`int x, int y`
`ResetSelection`	Resets the selection to its initial position and size.	`ValueTask`
`Rotate`	Rotates the image.	`ValueTask`	`double angle`
`Scale`	Scale the image.	`ValueTask`	`int x, int y`
`Zoom`	Zooms the image.	`ValueTask`	`double scale`

Blazorise Cropper component

Installation

NuGet

Imports

Message Size

Examples

Basic

Viewer

API

Parameters

Cropper

CropperViewer

CropperCropOptions

CropperImageOptions

CropperSelectionOptions

CropperGridOptions

Events

Cropper

Methods

Cropper

On this page