Status
ImageCropper
Crop a picture to a square before it's saved: a profile photo, a brand logo, the workspace logo.
Preview
Props
| Prop | Type | Description |
|---|---|---|
srcRequired | string | The picture to crop: a URL the page can read (an object URL for a new file). |
shape | 'circle' | 'square' | circle for photos of people (default), square for logos. The result is always a square. |
value | ImageCrop | The crop to start from, such as the one saved last time. Centered and fitted by default. |
onChange | (crop: ImageCrop) => void | |
onError | () => void | The picture can't be read (some HEIC files, a broken file). |
label | string | Name of the crop area for screen readers (default "Crop"). |
maxZoom | number | |
size | 'M' | 'L' | |
className | string |
Guidelines
Crop a picture to a square before it's saved: a profile photo, a brand logo, the workspace logo. Photos of people show the crop as a circle (the way the Avatar shows them); logos show the square.
Provide: src (a URL the page can read; an object URL for a file that was just picked), shape (circle or square), value and onChange (the crop, { x, y, zoom }), and onError for a picture the browser can't read.
- Moving it. Drag the picture inside the frame. The picture always covers the frame: it can't be dragged past its own edges.
- Zoom. The slider under the frame, its Zoom out and Zoom in buttons, or the wheel. 1 fits the shorter side; up to 4 by default (
maxZoom). - Keyboard. The frame takes focus: the arrow keys move the picture (Shift for bigger steps), and plus and minus zoom. Moves and zoom are announced.
- Saving.
ImageCropper.cropImage(src, crop, { size })draws the cropped square (512px and PNG by default, so logos keep their transparency) and resolves with a Blob to upload. - Cropping again. Keep the original picture beside the cropped one, and the crop with it, so cropping again starts where it was left and can zoom back out. Without an original, crop the saved picture.
- Put it in a Drawer with Save and Cancel. The dimmed corners use
scrim; nothing else is drawn over the picture. - Pictures only: PNG, JPG, WebP or GIF. Some HEIC files can't be read by every browser; say so plainly and ask for a JPG or PNG.