Cropper - Semi Design Next

When to use

Cropper is used to crop pictures. It supports custom cropping box styles. The positions of the cropping box, cropped image can be adjusted by dragging. It can zoom and rotate the cropped pictures.

Demos

How to import

import { Cropper } from '@fibrous/semi-ui-react';

Basic usage

Use src to set the cropped image; use shape to set the shape of the cropping box, which defaults to square.

rect

round

roundRect

Code

import { useState, useRef, useCallback } from 'react';
import { Cropper, Button, RadioGroup, Radio, type CropperHandle, type CropperProps, type RadioChangeEvent } from '@fibrous/semi-ui-react';

const containerStyle = {
    width: 550,
    height: 300,
    margin: 20,
};

export default function CropperDemo() {
    const ref = useRef<CropperHandle>(null);
    const [shape, setShape] = useState<CropperProps['shape']>('rect');
    const [cropperUrl, setCropperUrl] = useState('');

    const onButtonClick = useCallback(() => {
        const canvas = ref.current?.getCropperCanvas();
        if (canvas) setCropperUrl(canvas.toDataURL());
    }, []);

    const onShapeChange = useCallback((e: RadioChangeEvent) => {
        setShape(e.target.value);
    }, []);

    return (
        <>
            <RadioGroup aria-label="裁切框形状" onChange={onShapeChange} value={shape}>
                <Radio value="rect">rect</Radio>
                <Radio value="round">round</Radio>
                <Radio value="roundRect">roundRect</Radio>
            </RadioGroup>
            <Cropper ref={ref} src="/assets/other/image.png" style={containerStyle} shape={shape} />
            <Button onClick={onButtonClick}>裁切</Button>
            <br />
            <br />
            {cropperUrl && <img src={cropperUrl} alt="裁切结果" style={{ height: 400 }} />}
        </>
    );
}

Customize crop box ratio

The initial crop box ratio can be passed through defaultAspectRatio (default is 1). A fixed crop box ratio can be set via aspectRatio.

Setting defaultAspectRatio only takes effect on the initial crop box ratio. When dragging, the crop box ratio will change with dragging.

When setting aspectRatio, the crop box ratio is fixed, and the crop box will change according to this ratio when dragging. When aspectRatio changes after the image has loaded, the crop box is laid out again at the new ratio: its height is kept, its width follows the ratio, it shrinks to fit the container when it would overflow, and its center stays where it is as far as possible. When aspectRatio becomes undefined the box is not laid out again.

Code

import { useState, useRef, useCallback } from 'react';
import { Cropper, Button, type CropperHandle } from '@fibrous/semi-ui-react';

const containerStyle = {
    width: 550,
    height: 300,
    margin: 20,
};

export default function CropperDemo() {
    const ref = useRef<CropperHandle>(null);
    const [cropperUrl, setCropperUrl] = useState('');

    const onButtonClick = useCallback(() => {
        const canvas = ref.current?.getCropperCanvas();
        if (canvas) setCropperUrl(canvas.toDataURL());
    }, []);

    return (
        <>
            <Cropper aspectRatio={3 / 4} ref={ref} src="/assets/other/image.png" style={containerStyle} />
            <Button onClick={onButtonClick}>裁切</Button>
            <br />
            <br />
            {cropperUrl && <img src={cropperUrl} alt="裁切结果" style={{ height: 400 }} />}
        </>
    );
}

Controlled rotation/zooming of images

Control image rotation and zoom through rotate and zoom, and get the latest zoom value through onZoomChange

旋转

-360360

缩放

0.13

Code

import { useState, useRef, useCallback } from 'react';
import { Cropper, Button, Slider, type CropperHandle } from '@fibrous/semi-ui-react';

const containerStyle = {
    width: 550,
    height: 300,
    margin: 20,
};

const actionStyle = {
    marginTop: 20,
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    width: 'fit-content',
};

export default function CropperDemo() {
    const [rotate, setRotate] = useState(0);
    const [zoom, setZoom] = useState(1);
    const ref = useRef<CropperHandle>(null);
    const [cropperUrl, setCropperUrl] = useState('');

    const onZoomChange = useCallback((value?: number | number[]) => {
        if (typeof value === 'number') setZoom(value);
    }, []);

    const onSliderChange = useCallback((value?: number | number[]) => {
        if (typeof value === 'number') setRotate(value);
    }, []);

    const onButtonClick = useCallback(() => {
        const canvas = ref.current?.getCropperCanvas();
        if (canvas) setCropperUrl(canvas.toDataURL());
    }, []);

    return (
        <div id="cropper-container">
            <Cropper ref={ref} src="/assets/other/image.png" style={containerStyle} rotate={rotate} zoom={zoom} onZoomChange={onZoomChange} />
            <div style={actionStyle}>
                <span id="cropper-rotate-zoom-rotate">旋转</span>
                <Slider aria-labelledby="cropper-rotate-zoom-rotate" style={{ width: 500 }} value={rotate} step={1} min={-360} max={360} onChange={onSliderChange} />
            </div>
            <div style={actionStyle}>
                <span id="cropper-rotate-zoom-zoom">缩放</span>
                <Slider aria-labelledby="cropper-rotate-zoom-zoom" style={{ width: 500 }} value={zoom} step={0.1} min={0.1} max={3} onChange={onZoomChange} />
            </div>
            <br />
            <Button onClick={onButtonClick}>裁切</Button>
            <br />
            <br />
            {cropperUrl && <img src={cropperUrl} alt="裁切结果" style={{ height: 400 }} />}
        </div>
    );
}

Crop box settings

The crop box style can be customized through cropperBoxStyle, cropperBoxCls. You can use showResizeBox to set whether to display the adjustment blocks at the corners of the crop box.

showResizeBox = false，并修改边框颜色

Code

import { useState, useRef, useCallback } from 'react';
import { Cropper, Button, type CropperHandle } from '@fibrous/semi-ui-react';

const containerStyle = {
    width: 550,
    height: 300,
    margin: 20,
};

export default function CropperDemo() {
    const ref = useRef<CropperHandle>(null);
    const [cropperUrl, setCropperUrl] = useState('');

    const onButtonClick = useCallback(() => {
        const canvas = ref.current?.getCropperCanvas();
        if (canvas) setCropperUrl(canvas.toDataURL());
    }, []);

    return (
        <>
            <strong>showResizeBox = false，并修改边框颜色</strong>
            <Cropper ref={ref} src="/assets/other/image.png" style={containerStyle} cropperBoxStyle={{ outlineColor: 'var(--semi-color-bg-0)' }} showResizeBox={false} />
            <Button onClick={onButtonClick}>裁切</Button>
            <br />
            <br />
            {cropperUrl && <img src={cropperUrl} alt="裁切结果" style={{ height: 400 }} />}
        </>
    );
}

Live preview

Use preview to specify a container that previews the crop result in real time.

旋转

-360360

缩放

0.13

实时预览

Code

import { useState, useRef, useCallback } from 'react';
import { Cropper, Button, Slider, type CropperHandle } from '@fibrous/semi-ui-react';

const containerStyle = {
    width: 550,
    height: 300,
    margin: 20,
};

const actionStyle = {
    marginTop: 20,
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    width: 'fit-content',
};

export default function CropperDemo() {
    const [rotate, setRotate] = useState(0);
    const [zoom, setZoom] = useState(1);
    const [cropperUrl, setCropperUrl] = useState('');
    const ref = useRef<CropperHandle>(null);

    const onZoomChange = useCallback((value?: number | number[]) => {
        if (typeof value === 'number') setZoom(value);
    }, []);

    const onSliderChange = useCallback((value?: number | number[]) => {
        if (typeof value === 'number') setRotate(value);
    }, []);

    const onButtonClick = useCallback(() => {
        const canvas = ref.current?.getCropperCanvas();
        if (canvas) setCropperUrl(canvas.toDataURL());
    }, []);

    const preview = useCallback(() => {
        const previewContainer = document.getElementById('previewWrapper') as HTMLElement;
        return previewContainer;
    }, []);

    return (
        <div>
            <Cropper ref={ref} src="/assets/root-web-sites/abstract.jpg" style={containerStyle} rotate={rotate} zoom={zoom} onZoomChange={onZoomChange} preview={preview} />
            <div style={actionStyle}>
                <span id="cropper-preview-rotate">旋转</span>
                <Slider aria-labelledby="cropper-preview-rotate" style={{ width: 500 }} value={rotate} step={1} min={-360} max={360} onChange={onSliderChange} />
            </div>
            <div style={actionStyle}>
                <span id="cropper-preview-zoom">缩放</span>
                <Slider aria-labelledby="cropper-preview-zoom" style={{ width: 500 }} value={zoom} step={0.1} min={0.1} max={3} onChange={onZoomChange} />
            </div>
            <br />
            <div style={{ display: 'flex' }}>
                <div style={{ width: '50%', flexGrow: 1 }}>
                    <strong>实时预览</strong>
                    <div id="previewWrapper" style={{ height: 300, marginTop: 8 }} />
                </div>
                <div style={{ width: '50%', flexGrow: 1, paddingLeft: 10 }}>
                    <Button onClick={onButtonClick}>裁切</Button>
                    <br />
                    <br />
                    {cropperUrl && <img src={cropperUrl} alt="裁切结果" style={{ width: '90%' }} />}
                </div>
            </div>
        </div>
    );
}

API

Props

Property	Description	Type	Default
aspectRatio	Fixed aspect ratio of the crop box, kept while dragging. When it changes after loading, the box is laid out again at the new ratio.	`number`	-
className	Class name of the root element.	`string`	-
cropperBoxCls	Class name of the crop box.	`string`	-
cropperBoxStyle	Style of the crop box, merged with the size and offset the component computes; the size and offset win.	`React.CSSProperties`	-
defaultAspectRatio	Initial aspect ratio of the crop box, which changes while dragging.	`number`	`1`
fill	Fill color of the parts of the result that are not the image.	`string`	`"rgba(0, 0, 0, 0)"`
imgProps	Attributes passed to the `img` element being cropped. `src` comes from the `src` prop; `className` is merged with the component's own class name; `style` sits under the component's layout, so the size and offset win; `onLoad` is called after the component has handled the load; `alt` defaults to an empty string and `crossOrigin` to `anonymous`, and both can be overridden.	`Type`	-
maxZoom	Maximum zoom factor.	`number`	`3`
minZoom	Minimum zoom factor.	`number`	`0.1`
onZoomChange	Called with the new zoom when the wheel changes it.	`Type`	-
preview	Function returning the DOM element of the preview container; the crop result is mirrored into it in real time. It may return `null` while the container is not mounted yet.	`Type`	-
ref	Handle exposing the `getCropperCanvas` method for reading the crop result; it is not the root element.	`Type`	-
rotate	Image rotation angle in degrees. It is one-way: the component never changes it.	`number`	-
shape	Shape of the crop box: `rect`, `round` or `roundRect`.	`'rect' \| 'round' \| 'roundRect'`	`"rect"`
showResizeBox	Whether to show the resize handles on the corners of the crop box.	`boolean`	`true`
src	Address of the image to crop.	`string`	-
style	Style of the root element.	`React.CSSProperties`	-
zoom	Controlled zoom, applied on top of the initial scaling that fits the image into the cropper.	`number`	-
zoomStep	Zoom change per wheel step.	`number`	`0.1`

Methods

Method	Description	Type
getCropperCanvas	Draws the area inside the crop box, at the image's own resolution, onto a new canvas.	`Type`

Native attributes that the component does not declare (such as id, data-*, aria-* and onKeyDown) land on the root <div>; role can be overridden. ref gets the component handle, not the root element.

Accessibility

With aria-label or aria-labelledby and no role on the root, the root gets role="group"; a role you pass wins
The crop box is a focusable named group (role="group", with its name and role description from the locale, and aria-describedby pointing to the usage hint). It becomes focusable once the image has loaded. The img being cropped is decorative: its alt defaults to an empty string and can be overridden through imgProps
Only a mouse press with the primary button, or a touch or pen contact, starts dragging the crop box, a resize handle or the image; a middle or right mouse press does not

Keyboard and focus

The crop box is the only tab stop in the component, and is focusable only after the image has loaded
With focus on the crop box, each arrow key moves the box by 10px, and the box stays inside the container
Shift + arrow keys move the bottom right corner of the box by 10px to resize it, within the container; when aspectRatio is set the ratio is kept (a horizontal change is converted to height). This works only while showResizeBox is true (the handles are shown); with false, Shift + arrow keys do nothing
Zoom and rotation have no built-in keyboard control; provide a keyboard-operable control for them (such as the Slider in the demos)

Design Token

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.

Sass variable	Value	Usage
$color-cropper_mask-bg	var(--semi-color-overlay-bg)
$color-cropper_box-outline	var(--semi-color-primary)
$color-cropper_box_corner-bg	var(--semi-color-primary)
$width-cropper_box-outline	1px
$width-cropper_box_corner	10px