Skip to main content

Advanced Recipes

Fixed stencil#

There is the example of a fixed stencil below, that may be useful for mobile devices.

import { FixedCropper, ImageRestriction } from 'react-advanced-cropper';
<FixedCropper    src={'https://images.pexels.com/photos/5006465/pexels-photo-5006465.jpeg?auto=compress&cs=tinysrgb&h=750&w=1260'}    stencilSize={{        width: 300,        height: 300    }}    stencilProps={{        handlers: false,        lines: false,        movable: false,        resizable: false    }}    imageRestriction={ImageRestriction.stencil}/>

Default Coordinates#

Sometimes you should set the default position and default size of the cropped area. For example, if you automatically detect an user face. It can be achieved by using defaultSize and defaultPosition props.

import React from 'react';import { Cropper } from 'react-advanced-cropper';
export const Example = () => {    return (        <Cropper            src={'https://images.unsplash.com/photo-1599140849279-1014532882fe?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1300&q=80'}            defaultCoordinates={{                    left: 100,                    top: 100,                    width: 400,                    height: 400,            }}        />;    )};

Position / Size#

There are situations, when you need set either position or size. In this case defaultSize and defaultPosition can be very helpful. You can pass the objects or functions to them alike.

import React from 'react';import { Cropper } from 'react-advanced-cropper';
export const Example = () => {    return (        <Cropper            src={'https://images.unsplash.com/photo-1599140849279-1014532882fe?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1300&q=80'}            defaultPosition={{                    left: 100,                    top: 100,            }}        />;    )};

Fill the image#

The defaultSize prop can determine the default size based on the state as mentioned in its documentation.

It can be used to force the cropper fills all visible area by default:

import React from 'react';import { Cropper } from 'react-advanced-cropper';
export const Example = () => {    const defaultSize = ({ imageSize, visibleArea }) => {            return {                width: (visibleArea || imageSize).width,                height: (visibleArea || imageSize).height,            };    }    return (        <Cropper            src={'https://images.pexels.com/photos/6524107/pexels-photo-6524107.jpeg?auto=compress&cs=tinysrgb&dpr=2&h=650&w=940'}            defaultSize={defaultSize}        />;    )};

Default visible area#

Moreover, there are situations where you need to save, for example, previous visible area position, i.e. zoom or translate image. To implement it you can use defaultVisibleArea prop.

It should be noted, that visible area can be calculated either before default coordinates calculation or after one's calculation. The priority is set by prop priority that can be either Priority.coordinates (default) or Priority.visibleArea.

tip

If you define only the visible area coordinates it may be easier to set priority to Priority.visibleArea. It eliminates the necessity to set default coordinates by yourself. Default algorithms will handle this situation instead.

import React from 'react';import { Cropper, Priority } from 'react-advanced-cropper';
export const Example = () => {    const defaultVisibleArea = {        width: 800,        height: 775,        left: 63,        top: 668,    };    return (        <Cropper            src={                'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'            }            defaultVisibleArea={defaultVisibleArea}            priority={Priority.visibleArea}        />    );};

Move and scale image#

The cropper has two methods for move and scale image: moveImage and zoomImage.

The minimal working example:

import React from 'react';import { Cropper, CropperRef } from 'react-advanced-cropper';
export const Example = () => {    const cropperRef = useRef<CropperRef>(null);    const zoom = () => {        if (cropperRef.current) {            cropperRef.current.zoomImage(2); // zoom-in 2x        }    };    const move = () => {        if (cropperRef.current) {            cropperRef.current.moveImage(50, 100); // move x = 50, y = 100        }    };    return (        <Cropper            ref={cropperRef}            src={                'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'            }        />    );};

Rotate / flip image#

To rotate image use rotateImage method, it accepts two argument: rotate and options. They are described in the method documentation, but in the most cases you should pass only the desired rotate angle to first one as a number (in degrees).

Available Angles

It's strongly recommended to use an angle multiple of 90. Otherwise, the different restrictions may be broken.

To flip an image use flip method, it accepts the three arguments: horizontal, vertical and options. If first is equal to true then image will be flipped horizontally, if the second is equal to true then image will be flipped vertically and etc.

The minimal working example:

import React from 'react';import { Cropper, CropperRef } from 'react-advanced-cropper';
export const Example = () => {    const cropperRef = useRef<CropperRef>(null);    const flip = (horizontal: boolean, vertical: boolean) => {        if (cropperRef.current) {            cropperRef.current.flip(horizontal, vertical);        }    };    const rotate = (angle: number) => {        if (cropperRef.current) {            cropperRef.current.rotate(angle);        }    };    return (        <Cropper            ref={cropperRef}            src={                'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'            }        />    );};

Adjust Stencil#

Adjust stencil is the one of transformImage prop option. By default it's enabled. It makes cropper more convenient especially when you have the limitations of width / height.

Try to resize image when adjustStencil is disabled and enabled to feel the difference.

Set coordinates#

Usually an user changes the coordinates of a stencil, but sometimes you need to set its coordinates programmatically. There is the special method to do it: setCoordinates. It applies your changes respect to existing limitation (aspect ratios, minimum size and etc.)

The minimal working example:

import React from 'react';import { Cropper, CropperRef } from 'react-advanced-cropper';
export const Example = () => {    const cropperRef = useRef<CropperRef>(null);
    const resize(width, height, left, top) => {        if (cropperRef.current) {            cropperRef.current.setCoordinates({                width: width,                height: height,                left: left,                top: top            })        }    };
    return (        <Cropper            ref={cropperRef}            src={                'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'            }        />    );};

Different image restrictions#

You are able to set different the restrictions of an image position by passing the following string to the imageRestriction prop:

  • fillArea fill area by image and prevents resizing and moving the image beyond the area
  • fitArea fit image to area and prevents resizing and moving the image beyond the area as much as possible
  • stencil prevents resizing and moving the image beyond the stencil
  • none allows free resizing and moving the image

If you use TypeScript, you should use the corresponding enum value.

import { ImageRestriction } from 'react-advanced-cropper';
<Cropper imageRestriction={ImageRestriction.fillArea} />
Image Restriction Type
Download

Custom size restrictions#

There may be situations, when you need to set the minimum and maximum sizes, for example, in percents, not in pixels. In that situations you should redefine the sizeRestrictions functions by passing your custom function as a corresponding prop

Min width
Min height
Max width
Max height
Upload image
Download result
import React from 'react';import { Cropper, CropperRef, DefaultSettings } from 'react-advanced-cropper';import { getTransformedImageSize, retrieveSizeRestrictions } from 'advanced-cropper';
export const Example = () => {    const percentsRestriction = (state: CropperState, settings: DefaultSettings) => {        const { minWidth, minHeight, maxWidth, maxHeight } = retrieveSizeRestrictions(settings);
        const imageSize = getTransformedImageSize(state);
        return {            minWidth: (minWidth / 100) * imageSize.width,            minHeight: (minHeight / 100) * imageSize.height,            maxWidth: (maxWidth / 100) * imageSize.width,            maxHeight: (maxHeight / 100) * imageSize.height,        };    };
    return (        <Cropper            sizeRestrictions={percentsRestriction}            src={'https://images.unsplash.com/photo-1494205577727-d32e58564756?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=750&q=80'}        />    );};

Default transforms#

There are situations when you need to save the image transforms. In this case defaultTransforms can be useful.

It can be either a function or an object.

Default Transform
Upload image
import React from 'react';import { Cropper, CropperRef, retrieveSizeRestrictions, getTransformedImageSize } from 'react-advanced-cropper';
export const Example = () => {    const defaultTransforms = {        rotate: 90,        flip: {            horizontal: false,            vertical: false,        }    };
    return (        <Cropper            defaultTransforms={defaultTransforms}            src={'https://images.pexels.com/photos/1758144/pexels-photo-1758144.jpeg?auto=compress&cs=tinysrgb&dpr=2&h=650&w=940'}        />    );};

Dynamic cropper size#

There are situations, when a cropper container size is changed. It's can't be handle by cropper itself, because it doesn't know about this changes at all (in contradistinction to window's resize), so you should call refresh method.

tip

This situation may seems unlikely, but in fact if your cropper was in a container that was, for example, hidden by display: none, you should call refresh method after its appearing.

There is a minimal example:

<Cropper ref={cropperRef}/>
// On some change, that causes container's size changecropperRef.current.refresh();

Scroll the cropper#

Sometimes, there are situations, where an user can scroll the page and accidentally stops the scrolling when cursor happens to be placed on the cropper. This default behavior is the result of preventing all default mouse and touch events in the cropper background wrapper.

However, this behavior can be easily redefined by replacing the default CropperBackgroundWrapper by the custom one.

The source code of this example is available in the sandbox.

Use ctrl + scroll to zoom the cropper