# @wordpress/image-cropper

> A basic image cropper component.

Latest version **1.19.0** (published 2026-09-10) · GPL-2.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @wordpress/image-cropper
pnpm add @wordpress/image-cropper
yarn add @wordpress/image-cropper
bun add @wordpress/image-cropper
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.19.0 |
| Published | 2026-09-10 |
| First published | 2025-12-09 |
| Weekly downloads | 0 |
| License | GPL-2.0-or-later |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.12.0 |
| Dependencies | 5 |
| Unpacked size | 152.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11747 |
| Author | The WordPress Contributors |
| Maintainers | garypendergast, adamsilverstein, gziolo, ntwb, riad, noisysocks, kadamwhite, gutenbergplugin, jorgefilipecosta, ellatrix, iandunn206, whyisjake, ockham, sirreal, nosolosw, wpisabel, ntsekouras, nerrad, desrosj, talldanwp, peterwilsoncc, ryanwelcher, mamaduka, aduth, johnbillion |
| Keywords | wordpress, gutenberg, image cropper, cropper |

## Links

- npm: https://www.npmjs.com/package/@wordpress/image-cropper
- Repository: https://github.com/WordPress/gutenberg
- Homepage: https://github.com/WordPress/gutenberg/tree/HEAD/packages/image-cropper/README.md
- Issues: https://github.com/WordPress/gutenberg/issues
- npm.io page: https://npm.io/package/@wordpress/image-cropper

## Dependencies (5)

- [dequal](https://npm.io/package/dequal.md) ^2.0.3
- [@wordpress/i18n](https://npm.io/package/@wordpress/i18n.md) ^6.28.0
- [react-easy-crop](https://npm.io/package/react-easy-crop.md) ^5.4.2
- [@wordpress/element](https://npm.io/package/@wordpress/element.md) ^8.7.0
- [@wordpress/components](https://npm.io/package/@wordpress/components.md) ^40.1.0

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 1.19.0 (latest) — 2026-09-10
- 1.19.1-next.v.202609171837.0 (next) — 2026-09-17
- 1.4.1 (wp-7.0) — 2026-06-30
- 1.18.2-next.v.202609031004.0 — 2026-09-03
- 1.18.2-next.v.202608281122.0 — 2026-08-28
- 1.18.0 — 2026-08-26
- 1.17.0 — 2026-08-12
- 1.16.0 — 2026-07-29
- 1.15.0 — 2026-07-14
- 1.14.1-next.v.202607070741.0 — 2026-07-07
- 1.14.0 — 2026-07-01
- 1.13.1 — 2026-06-30
- 1.13.0 — 2026-06-24
- 1.12.2-next.v.202606191442.0 — 2026-06-19
- 1.12.1 — 2026-06-16
- … 35 more at https://npm.io/package/@wordpress/image-cropper/versions

## README

# Image Cropper

An implementation of [react-easy-crop](https://www.npmjs.com/package/react-easy-crop).

## Current features

-   **Image Cropping**: Interactive aspect ratio-based crop area with drag and resize functionality
-   **Rotation**: Rotate images in 90-degree increments
-   **Zoom Control**: Zoom in/out with configurable min/max limits
-   **Aspect Ratio**: Set and maintain specific aspect ratios
-   **Flip Controls**: Horizontal and vertical image flipping
-   **State Management**: Centralized state management with React Context
-   **Custom Reset State**: Configure custom initial states for reset operations

## Future features

-   [ ] Freeform cropping

## Installation

Install the module

```bash
npm install @wordpress/image-cropper --save
```

## API

### Components

-   `ImageCropper` - The main cropping component that provides the cropping canvas.

```tsx
interface ImageCropperProps {
	src: string; // Image source URL
	onLoad?: ( mediaSize: MediaSize ) => void; // Callback when image loads with media dimensions
	minZoom?: number; // Minimum zoom level (default: 1)
	maxZoom?: number; // Maximum zoom level (default: 5)
}
```

-   `ImageCropperProvider` - Context provider for state management. This component implements the React Context pattern to share cropper state across your application. It manages all internal cropper state including crop position, zoom levels, rotation, flip transformations, aspect ratios, and media dimensions. Any component that needs to read or modify cropper state must be a descendant of this provider. The provider also handles state persistence and provides methods for resetting to custom initial states.

### Hooks

-   `useImageCropper` - Provides access to all cropper state and methods.

```tsx
import { useImageCropper } from '@wordpress/image-cropper';

const {
	// Unified state object
	cropperState, // Complete cropper state { crop, croppedArea, croppedAreaPixels, zoom, rotation, aspectRatio, flip, mediaSize }
	setCropperState, // Set multiple state properties at once

	// Actions
	reset, // Reset all changes (uses resetState if set)
	setResetState, // Set custom reset state
	getCroppedImage, // Get cropped image as data URL

	// Reset state
	resetState, // Current reset state configuration
	isDirty, // Whether the state is dirty based on resetState or default settings
} = useImageCropper();
```

### Types

-   `ImageCropperState` - State interface for cropper data
-   `ImageCropperProps` - Props interface for ImageCropper component
-   `ImageCropperContextValue` - Context value interface
-   `Flip` - Flip state interface
-   `Point`, `Area`, `MediaSize` - Re-exported from react-easy-crop

### Utilities

-   `normalizeRotation` - Utility function to normalize rotation values to 0-360 degrees

```tsx
import { normalizeRotation } from '@wordpress/image-cropper';

const normalized = normalizeRotation( -90 ); // Returns 270
const normalized2 = normalizeRotation( 450 ); // Returns 90
```

## Usage

### Basic Implementation

The image cropper provides the core cropping functionality without any built-in UI controls. You must implement your own tools using the `useImageCropper` hook.

```tsx
import {
	ImageCropper,
	ImageCropperProvider,
	useImageCropper,
} from '@wordpress/image-cropper';

function ImageEditor() {
	return (
		<ImageCropperProvider>
			<div className="image-editor">
				<ImageCropper
					src="https://example.com/image.jpg"
					className="image-cropper"
					onLoad={ ( mediaSize ) =>
						console.log( 'Image loaded', mediaSize )
					}
				/>
				<ImageEditorTools />
			</div>
		</ImageCropperProvider>
	);
}

function ImageEditorTools() {
	const { cropperState, setCropperState, reset, setResetState } =
		useImageCropper();

	const { zoom, rotation, aspectRatio, flip, mediaSize, croppedArea } =
		cropperState;

	const handleSave = () => {
		console.log( 'Cropper state:', {
			crop: croppedArea,
			zoom,
			rotation,
			aspectRatio,
			flip,
		} );
		// Apply the crop state to your image
	};

	return (
		<div className="image-editor-tools">
			<button
				onClick={ () => setCropperState( { rotation: rotation + 90 } ) }
			>
				Rotate Right
			</button>
			<button
				onClick={ () => setCropperState( { rotation: rotation - 90 } ) }
			>
				Rotate Left
			</button>
			<button
				onClick={ () =>
					setCropperState( {
						flip: { ...flip, horizontal: ! flip.horizontal },
					} )
				}
			>
				Flip Horizontal
			</button>
			<button
				onClick={ () =>
					setCropperState( {
						flip: { ...flip, vertical: ! flip.vertical },
					} )
				}
			>
				Flip Vertical
			</button>
			<button onClick={ handleSave }>Apply Changes</button>
			<button onClick={ reset }>Reset</button>
		</div>
	);
}
```

### Advanced Usage with Custom Reset State

You can configure a custom initial state that will be used when the reset function is called:

```tsx
function ImageEditorWithCustomReset() {
	const { setResetState, reset } = useImageCropper();

	// Set custom reset state
	useEffect( () => {
		setResetState( {
			rotation: 90,
			zoom: 1.5,
			aspectRatio: 16 / 9,
			flip: { horizontal: false, vertical: false },
		} );
	}, [ setResetState ] );

	return (
		<div>
			{ /* Your cropper components */ }
			<button onClick={ reset }>Reset to Custom State</button>
		</div>
	);
}
```

---
_Source: https://npm.io/package/@wordpress/image-cropper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._