react-crop-kit

A responsive image and video crop component for React 19. Drag to draw, resize with handles, nudge with the keyboard, and keep the selection in pixels or percentages.

Install

pnpm add react-crop-kit
# or npm install react-crop-kit / yarn add react-crop-kit

Peer dependencies: react and react-dom (^19).

Setup

Import the component — default styles are injected automatically at runtime:

import { ReactCropKit } from "react-crop-kit";

Basic usage

ReactCropKit is controlled: pass crop from state and update it in onChange.

import { useState } from "react";
import { ReactCropKit, type Crop } from "react-crop-kit";

function ImageCropper({ src }: { src: string }) {
  const [crop, setCrop] = useState<Crop>();

  return (
    <ReactCropKit
      crop={crop}
      onChange={(_pixelCrop, percentCrop) => setCrop(percentCrop)}
    >
      <img src={src} alt="Crop me" />
    </ReactCropKit>
  );
}

onChange receives two shapes:

• PixelCrop — unit: "px", useful for canvas export
• PercentCrop — unit: "%", scales when the media is resized

Storing the percent crop in state (as above) is the usual choice.

Fixed aspect ratio

Pass aspect (width ÷ height). Examples: 1 for a square, 16 / 9 for landscape.

<ReactCropKit
  aspect={16 / 9}
  crop={crop}
  onChange={(_pixel, percent) => setCrop(percent)}
>
  <img src={src} alt="" />
</ReactCropKit>

Initial crop

When you set crop for the first time (e.g. after load), onComplete runs once if it was previously unset — handy for previews.

Helpers centerCrop and makeAspectCrop (plus convertToPercentCrop / convertToPixelCrop) ship from the same package:

import {
  ReactCropKit,
  centerCrop,
  makeAspectCrop,
  type Crop,
} from "react-crop-kit";

function onImageLoad(e: React.SyntheticEvent<HTMLImageElement>) {
  const { width, height } = e.currentTarget;
  setCrop(
    centerCrop(
      makeAspectCrop({ unit: "%", width: 90 }, 16 / 9, width, height),
      width,
      height,
    ),
  );
}

Or set a crop manually:

const [crop, setCrop] = useState<Crop>({
  unit: "%",
  x: 10,
  y: 10,
  width: 80,
  height: 80,
});

<ReactCropKit
  crop={crop}
  onChange={(_, percent) => setCrop(percent)}
  onComplete={(pixel, percent) => {
    console.log("Ready", pixel, percent);
  }}
>
  <img src={src} alt="" />
</ReactCropKit>

All of x, y, width, and height are required on the crop object when you use one (except you may omit aspect on the prop).

Props

Prop	Type	Description
crop	Crop	Controlled selection. Omit to hide the crop UI.
onChange	(pixel, percent) => void	Required. Called on every change.
onComplete	(pixel, percent) => void	After drag, resize, or keyboard nudge ends.
onDragStart	(e: PointerEvent) => void	First pointer move after press.
onDragEnd	(e: PointerEvent) => void	Pointer up after drag or resize.
aspect	number	Lock aspect ratio (e.g. 1, 16/9).
circularCrop	boolean	Circular mask (oval if aspect ≠ 1).
ruleOfThirds	boolean	Show rule-of-thirds guides.
disabled	boolean	No interaction; adds ReactCropKit--disabled.
locked	boolean	No new crop or resize; can still drag selection.
keepSelection	boolean	Clicking outside does not clear the crop.
minWidth / minHeight	number	Minimum size in pixels.
maxWidth / maxHeight	number	Maximum size in pixels.
className	string	Extra class on the root element.
styles	CSSProperties	Inline styles on the root.
ariaLabels	object	Override default English a11y strings.
renderSelectionAddon	(state) => ReactNode	Custom overlay inside the selection.

ReactCropKitState passed to renderSelectionAddon:

• cropIsActive — user is dragging or resizing
• newCropIsBeingDrawn — drawing a new region

Keyboard

Focus the crop area or a handle, then:

Keys	Action
Arrow keys	Move crop or resize from focused handle
Shift + arrows	10px step
Ctrl/Cmd + arrows	100px step

Styling

Styles ship with the bundle and are applied when you import react-crop-kit (no separate CSS import required). To load styles as a static stylesheet instead — for example in SSR or when your bundler strips runtime injection — import react-crop-kit/styles.css explicitly.

Override defaults via your own CSS targeting classes such as:

• .ReactCropKit
• .ReactCropKit__crop-selection
• .ReactCropKit--disabled, .ReactCropKit--locked, .ReactCropKit--circular-crop

CSS variables on :root:

• --rck-drag-handle-size
• --rck-drag-handle-mobile-size
• --rck-border-color
• --rck-focus-color

Exporting the cropped image

Use the pixel crop from onChange / onComplete with a canvas:

function cropImage(
  image: HTMLImageElement,
  pixelCrop: { x: number; y: number; width: number; height: number },
): Promise<Blob> {
  const canvas = document.createElement("canvas");
  const scaleX = image.naturalWidth / image.width;
  const scaleY = image.naturalHeight / image.height;

  canvas.width = pixelCrop.width * scaleX;
  canvas.height = pixelCrop.height * scaleY;

  const ctx = canvas.getContext("2d")!;
  ctx.drawImage(
    image,
    pixelCrop.x * scaleX,
    pixelCrop.y * scaleY,
    pixelCrop.width * scaleX,
    pixelCrop.height * scaleY,
    0,
    0,
    canvas.width,
    canvas.height,
  );

  return new Promise((resolve) =>
    canvas.toBlob((blob) => resolve(blob!), "image/png"),
  );
}

Scale by naturalWidth / width when the displayed image is scaled (responsive layouts).

Development

pnpm install
pnpm run build      # dist/
pnpm run typecheck
pnpm run dev        # watch build

License

MIT © Sunil Nune