Image Cropper

ProNew

Crop, zoom and rotate an image with Cropper.js 2: aspect-ratio choices, a round avatar mask, keyboard and button controls for every move, a live size readout and a Blob result at the size you choose.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/image-cropper

Usage

Cropper.js is imported when the component mounts (await import("cropperjs")), so it stays out of your initial bundle and the component is safe to render on the server. An image from another origin needs CORS headers (Access-Control-Allow-Origin), or the browser blocks reading its pixels.

Props

Prop	Type	Default	Description
`src`	`string`	-	Image URL or object URL.
`aspectRatio`	`number \| null`	`null`	Start ratio (width over height).
`aspectOptions`	`{ label, value }[]`	Free, 1:1, 4:3, 16:9	The ratio buttons.
`round`	`boolean`	`false`	Circle mask, 1:1.
`maxOutputWidth`	`number`	native	Output width cap in px.
`outputType`, `quality`	`image/png`, `image/jpeg`, `image/webp`; `number`	`image/png`, `0.92`	Encoding.
`height`	`number`	`320`	Height of the editing area.
`onCrop`	`({ blob, url, width, height }) => void`	-	Called with the result.
`onCancel`, `cropLabel`			Optional Cancel button and the Crop button text.

Accessibility

The edit area is a focusable group. While it has focus, the arrow keys move the crop box, and + and - resize it (Cropper.js keyboard mode, switched on at focus and off at blur so it never captures keys elsewhere on the page).
Every pointer action has a labelled button: move the crop area in four directions, make it larger or smaller, zoom in and out, rotate left and right, reset. A live region says what changed.
The aspect ratio is a single-choice toggle group with a name; the selected size is printed as text ("480 x 270 px selected").
A failure to open or encode the image is a role="alert" message. Offer a way to skip cropping in your flow for anyone who cannot use the tool.
Cropper.js draws on a canvas and its handles do not animate; there is no motion to turn off.

Testing

The component ships with a Testing Library test (image-cropper.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/image-cropper

Usage

Props

Prop	Type	Default	Description
`src`	`string`	-	Image URL or object URL.
`aspectRatio`	`number \| null`	`null`	Start ratio (width over height).
`aspectOptions`	`{ label, value }[]`	Free, 1:1, 4:3, 16:9	The ratio buttons.
`round`	`boolean`	`false`	Circle mask, 1:1.
`maxOutputWidth`	`number`	native	Output width cap in px.
`outputType`, `quality`	`image/png`, `image/jpeg`, `image/webp`; `number`	`image/png`, `0.92`	Encoding.
`height`	`number`	`320`	Height of the editing area.
`onCrop`	`({ blob, url, width, height }) => void`	-	Called with the result.
`onCancel`, `cropLabel`			Optional Cancel button and the Crop button text.

Accessibility

The edit area is a focusable group. While it has focus, the arrow keys move the crop box, and + and - resize it (Cropper.js keyboard mode, switched on at focus and off at blur so it never captures keys elsewhere on the page).
Every pointer action has a labelled button: move the crop area in four directions, make it larger or smaller, zoom in and out, rotate left and right, reset. A live region says what changed.
The aspect ratio is a single-choice toggle group with a name; the selected size is printed as text ("480 x 270 px selected").
A failure to open or encode the image is a role="alert" message. Offer a way to skip cropping in your flow for anyone who cannot use the tool.
Cropper.js draws on a canvas and its handles do not animate; there is no motion to turn off.

Testing

The component ships with a Testing Library test (image-cropper.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.