Image cropper

A React component in Beamline's Form controls category.

Frame a picture before it is saved: a fixed window (square, round for avatars, wide for covers, or free with handles) over the picture, which you drag, zoom with the slider, wheel or a pinch, and turn a quarter at a time; it always covers the window, thirds lines show while you move it, and the arrow keys, + and − and R do the same from the keyboard. cropImage turns the result into a file.

Use it for

Before saving a profile picture, a workspace logo or a cover image: the person chooses what part of the picture shows.
Fitting any uploaded picture to the shape it will be shown in.

Not for

Choosing the files (file-dropzone, then crop the picture chosen).
Comparing two pictures (image-compare).
Viewing pictures full screen (lightbox).

Anatomy

stage: the picture under a dimmed surround, the crop window cut out of it (a circle for round), a size container that keeps its own aspect
thirds lines inside the window, shown while the picture is moved or zoomed
handles at the window's corners when the aspect is free
toolbar: zoom slider between a smaller and a larger picture glyph, Rotate, Reset
live line for assistive tech: zoom and rotation after keyboard changes

Variants

shape: rect, round
aspect: 1, 16/9, 3/1 (cover), free

States

loading (the picture's shape held, no surround yet)
ready
moving (thirds shown)
zoomed
rotated
failed to load (says so)
disabled
A free-crop corner keeps its pointer origin across renders, so consecutive drag moves follow the pointer without jumping.

Keyboard

Tab reaches the stage: ← → ↑ ↓ move the picture (Shift: ten times as far), + and − zoom, R turns it a quarter, 0 resets
Tab then reaches the zoom slider, Rotate and Reset
With a free aspect each corner handle is a stop: the arrow keys resize the window from that corner

Motion

Dragging, a pinch and the wheel follow the hand at once. The zoom slider eases the picture to each step (critically damped), Rotate turns it a quarter on the same ease, and Reset settles it back to fill the window. Thirds lines fade in while it moves and out a moment after. The picture never leaves the window uncovered: a drag past the edge stops at the edge. Reduced motion: every change is instant.

Props

Prop	Type	Default	Description
`src` (required)	`string`	—
`alt`	`string`	—	What the picture shows; names the stage for assistive tech.
`aspect`	`number \| "free"`	—	Width over height of the window. Default 1.
`shape`	`"rect" \| "round"`	—	round draws a circle (aspect 1).
`value / defaultValue / onValueChange`	`CropValue`	—
`onValueCommit`	`(value: CropValue) => void`	—	When a drag, pinch, key or slider move ends.
`minZoom / maxZoom`	`number`	—	Default 1 and 4.
`toolbar`	`boolean`	—	Show the zoom slider, Rotate and Reset. Default true.
`disabled`	`boolean`	—
`className / classNames / style / ref`	`root`	—

Built from

slider
button

Dependencies

lucide-react, @radix-ui/react-slider

Import

import { ImageCropper } from "@/components/image-cropper/image-cropper";

Get it

Image cropper is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. Get Beamline · Connect your agent