@rozie-ui/cropper-react

Idiomatic react Cropper — a cross-framework image cropper compiled from one Rozie source wrapping Cropper.js (v1). The crop box is two-way bound via data ({ x, y, width, height, rotate, scaleX, scaleY }). This package is generated; do not edit src/ by hand.

Install

npm i @rozie-ui/cropper-react

Peer dependencies: the cropperjs engine (^1) + react + react-dom. Install them alongside this package.

Also installed: @rozie/runtime-react — Rozie's small, tree-shaken runtime helper package (controllable state, keyboard navigation, event modifiers, and safe interpolation). It arrives as a regular dependency, so npm pulls it for you. Your bundler keeps only the helpers this component actually uses — typically a few hundred bytes to a few KB, minified and gzipped. What's in it and what it costs.

Import the engine CSS once at your app entry (the scoped component <style> cannot reach the engine-rendered .cropper-* crop UI):

import 'cropperjs/dist/cropper.css';

Usage

import { useState } from 'react';
import { Cropper } from '@rozie-ui/cropper-react';
import 'cropperjs/dist/cropper.css';

export function Demo() {
  const [data, setData] = useState();
  return (
    <Cropper
      src="/photo.jpg"
      data={data}
      onDataChange={setData}
      aspectRatio={16 / 9}
      viewMode={1}
      onCrop={(e) => console.log(e)}
    />
  );
}

Props

| Name | Type | Default | Two-way (model) | Required | | --- | --- | --- | :---: | :---: | | src | String | "" | | | | data | unknown | undefined | ✓ | | | aspectRatio | Number | NaN | | | | viewMode | Number | 0 | | | | dragMode | String | "crop" | | | | disabled | Boolean | false | | | | guides | Boolean | true | | | | center | Boolean | true | | | | background | Boolean | true | | | | movable | Boolean | true | | | | rotatable | Boolean | true | | | | scalable | Boolean | true | | | | zoomable | Boolean | true | | | | zoomOnWheel | Boolean | true | | | | cropBoxMovable | Boolean | true | | | | cropBoxResizable | Boolean | true | | | | autoCrop | Boolean | true | | | | autoCropArea | Number | 0.8 | | | | responsive | Boolean | true | | | | preview | unknown | undefined | | | | options | Object | {} | | |

Events

| Event | Description | | --- | --- | | ready | | | cropstart | | | cropmove | | | cropend | | | crop | | | zoom | |

Imperative handle

Beyond props, the component exposes imperative methods (declared once in the Rozie source via $expose). Grab a handle with the native ref mechanism and call them directly:

import { useRef } from 'react';
import { Cropper, type CropperHandle } from '@rozie-ui/cropper-react';

const cropper = useRef<CropperHandle>(null);
// <Cropper ref={cropper} ... />
const url = cropper.current?.getCroppedDataURL();
cropper.current?.rotateBy(90);

| Method | Description | | --- | --- | | getCropper | Return the underlying Cropper.js instance for direct API access (the engine escape hatch). | | getData | Return the current crop box as { x, y, width, height, rotate, scaleX, scaleY } — getData(rounded?) (pass true to round to whole pixels). Null before mount. | | getCanvasData | Return the canvas (wrapped image) position/size as { left, top, width, height, naturalWidth, naturalHeight }. Null before mount. | | getCropBoxData | Return the crop-box position/size in canvas pixels as { left, top, width, height }. Null before mount. | | getImageData | Return the image data as { left, top, width, height, rotate, scaleX, scaleY, naturalWidth, naturalHeight, aspectRatio }. Null before mount. | | getContainerData | Return the container size as { width, height }. Null before mount. | | getCroppedCanvas | Return an HTMLCanvasElement drawn from the cropped area — getCroppedCanvas(opts?) (Cropper GetCroppedCanvasOptions). Null before mount. | | getCroppedDataURL | Convenience: the cropped area as a toDataURL() string — getCroppedDataURL(opts?) (same options as getCroppedCanvas). Null before mount. | | reset | Reset the image and crop box to their initial states. | | clear | Clear (hide) the crop box. Pair with showCropBox() to re-show it. | | showCropBox | Show the crop box (Cropper crop()) — re-enables cropping after clear(). | | replace | Replace the image with a new source URL — replace(url). | | rotateTo | Rotate the image to an absolute degree — rotateTo(deg). | | rotateBy | Rotate the image by a relative degree (Cropper rotate()) — rotateBy(deg). | | zoomTo | Zoom the canvas to an absolute ratio — zoomTo(ratio, pivot?) (optional { x, y } zoom pivot). | | zoomBy | Zoom the canvas by a relative ratio (Cropper zoom()) — zoomBy(ratio). | | scaleX | Flip/scale the image horizontally — scaleX(n) (e.g. -1 to flip). | | scaleY | Flip/scale the image vertically — scaleY(n) (e.g. -1 to flip). | | scale | Scale (flip) the image on both axes — scale(scaleX, scaleY?); scaleY defaults to scaleX. | | setCanvasData | Set the canvas position/size — setCanvasData({ left?, top?, width?, height? }). | | setCropBoxData | Set the crop-box position/size — setCropBoxData({ left?, top?, width?, height? }). | | moveTo | Move the canvas to an absolute position — moveTo(x, y?) (y defaults to x). | | move | Move the canvas by a relative offset — move(offsetX, offsetY?) (offsetY defaults to offsetX). | | enable | Enable (unfreeze) the cropper. | | disable | Disable (freeze) the cropper. | | setAspectRatio | Set the crop box aspect ratio — setAspectRatio(ratio) (NaN for free). | | setDragMode | Set the drag mode — setDragMode('crop' | 'move' | 'none'). |