Skip to content
Mosaic
On this page

ImageCropper

Headless, unstyled square image cropper. The user pans by dragging or with the arrow keys, zooms with the wheel, a pinch, the keyboard, a slider or step buttons, turns the image a quarter at a time, and resets it. The crop is a Crop ({ x, y, zoom, rotation }), with zoom clamped between the zoom where the whole image fits in the frame and maxZoom. At zoom 1 and above the image covers the frame. Below 1 the frame shows empty space along the short side of the image, and the long side stays cropped until the minimum zoom, where the whole image fits. cropImage(src, crop, { type, size }) draws the chosen square into a Blob. Every control stays disabled until the image has loaded.

Use for

  • cropping a picked image to a square before upload
  • pan, zoom and rotate controls for an image
  • drawing a cropped image to a blob

Practices

GuidancePractice
Don’tBuild an avatar or logo crop dialog from it. Use AvatarUpload, which already wraps the cropper.
DoGive Viewport an aria-label that names the keys. It has role="application" and the image has an empty alt.
DoGive icon-only ZoomIn, ZoomOut, Rotate and Reset buttons an aria-label.
DoSize the frame, any mask and the controls yourself. The primitive emits no styles apart from placing the image.
DoRead the output type from the blob cropImage returns. A browser that cannot encode type returns image/png.

API reference

ImageCropper.Root

Owns the crop and the image size and provides them to the parts. Renders no element.

PropTypeDescription
srcstringThe image to crop, such as an object URL for a picked file.
valueCropThe crop, when controlled.
defaultValueCropThe crop on mount, when uncontrolled.Default: `INITIAL_CROP`
onValueChange(crop: Crop) => voidCalled with the next crop on every pan, zoom, turn and reset.
maxZoomnumberLargest zoom, as a multiple of the scale that covers the frame.Default: 4
disabledbooleanIgnores every gesture and disables the controls.Default: false

ImageCropper.Viewport

The frame, a div with role="application". Pans on drag and arrow keys (Shift for more), zooms on wheel, pinch and +/-, resets on 0. Leaves the tab order until the image loads. Carries data-dragging and data-disabled.

ImageCropper.Area

Optional div marking the square that is cropped when it is smaller than the frame. Drags are measured against it, and the Viewport around it shows the rest of the image.

ImageCropper.Image

The img, placed by the crop and hidden until loaded. Reports its size on load and carries data-loaded.

ImageCropper.Zoom

An input type="range" from the zoom where the whole image fits to maxZoom. Carries data-disabled.

ImageCropper.ZoomIn

A button that zooms in one ZOOM_STEP. Disabled at maxZoom. Carries data-disabled.

ImageCropper.ZoomOut

A button that zooms out one ZOOM_STEP. Disabled once the whole image fits in the frame. Carries data-disabled.

ImageCropper.Rotate

A button that turns the image a quarter clockwise. Carries data-disabled.

ImageCropper.Reset

A button that returns to INITIAL_CROP. Carries data-disabled.

Examples

Crop and save

TSX
const [crop, setCrop] = useState<Crop>(INITIAL_CROP);

<ImageCropper.Root src={src} value={crop} onValueChange={setCrop}>
  <ImageCropper.Viewport aria-label='Crop. Drag or use the arrow keys to move, plus and minus to zoom.'>
    <ImageCropper.Area>
      <ImageCropper.Image />
    </ImageCropper.Area>
  </ImageCropper.Viewport>
  <ImageCropper.ZoomOut aria-label='Zoom out'>−</ImageCropper.ZoomOut>
  <ImageCropper.Zoom aria-label='Zoom' />
  <ImageCropper.ZoomIn aria-label='Zoom in'>+</ImageCropper.ZoomIn>
  <ImageCropper.Rotate>Rotate</ImageCropper.Rotate>
  <ImageCropper.Reset>Reset</ImageCropper.Reset>
  <button onClick={async () => onSave(await cropImage(src, crop, { type: 'image/png' }))}>Save</button>
</ImageCropper.Root>