npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

cropperjs-react-wrapper

v1.3.0

Published

A modern, lightweight React wrapper for Cropper.js v2 with TypeScript support

Readme

Cropper.js React

A modern, lightweight React wrapper for Cropper.js v2.

Features

  • ⚛️ React Support: Compatible with React 18 and React 19.
  • 📦 Cropper.js v2: Image transformations, crop constraints, and live previews.
  • 🧩 Component-Based: Compose your cropper from image, selection, handle, and preview components.
  • 🟦 TypeScript: Fully typed props, refs, and events.
  • 🚀 ESM Only: Modern module format.

Installation

npm install cropperjs-react-wrapper cropperjs
# or
yarn add cropperjs-react-wrapper cropperjs
# or
pnpm add cropperjs-react-wrapper cropperjs
# or
bun add cropperjs-react-wrapper cropperjs

Usage

Basic Example

import {
  CropperCanvas,
  CropperImage,
  CropperSelection,
  CropperHandle,
  CropperGrid,
  CropperCrosshair,
} from "cropperjs-react-wrapper";

export default function App() {
  return (
    <div style={{ width: "100%", height: 400 }}>
      <CropperCanvas background>
        <CropperImage
          src="https://fengyuanchen.github.io/cropperjs/images/picture.jpg"
          alt="Picture"
          initialFit="contain"
          rotatable
          scalable
          skewable
          translatable
        />
        <CropperSelection initialCoverage={0.5} movable resizable zoomable>
          <CropperGrid role="grid" covered bordered />
          <CropperCrosshair centered />
          <CropperHandle action="move" themeColor="rgba(255, 255, 255, 0.35)" />
          <CropperHandle action="ne-resize" />
          <CropperHandle action="nw-resize" />
          <CropperHandle action="se-resize" />
          <CropperHandle action="sw-resize" />
        </CropperSelection>
      </CropperCanvas>
    </div>
  );
}

Components

Each component wraps a Cropper.js custom element:

| Component | Cropper.js Element | Description | | ------------------ | --------------------- | --------------------------------------------------------- | | CropperCanvas | <cropper-canvas> | The main container for the cropper. | | CropperImage | <cropper-image> | The image to be cropped. Supports transformations. | | CropperSelection | <cropper-selection> | The crop box selection area. | | CropperGrid | <cropper-grid> | A grid displayed within the selection. | | CropperCrosshair | <cropper-crosshair> | A crosshair displayed within the selection. | | CropperHandle | <cropper-handle> | Interactive handles for resizing or moving the selection. | | CropperShade | <cropper-shade> | An overlay shade for the non-selected area. | | CropperViewer | <cropper-viewer> | A live view of a cropper selection. |

Accessing Methods

Use React refs to access methods such as $rotate, $scale, and $toCanvas.

import type { CropperImage as CropperImageElement } from "cropperjs";
import { useRef } from "react";
import { CropperCanvas, CropperImage } from "cropperjs-react-wrapper";

function RotateExample() {
  const imageRef = useRef<CropperImageElement>(null);

  return (
    <>
      <button onClick={() => imageRef.current?.$rotate("90deg")}>Rotate</button>
      <CropperCanvas>
        <CropperImage ref={imageRef} src="/photo.jpg" rotatable />
      </CropperCanvas>
    </>
  );
}

Image Sizing

Use initialFit to fit the image to its canvas, minFit and maxFit to limit its size, and inset limits to constrain its position.

CropperImage also exposes the native image properties supported by Cropper.js: crossOrigin, decoding, elementTiming, fetchPriority, loading, referrerPolicy, sizes, and srcSet. Every wrapper exposes the shared slottable property.

<CropperImage
  src="/photo.jpg"
  initialFit="cover"
  minFit="contain"
  maxFit="none"
/>

Selection and Image Controls

| Component | Props | Default | | ------------------ | ---------------------------------------- | ------------------------------------------- | | CropperImage | minInset, maxInset | "auto" | | CropperImage | zoomAroundCenter | false | | CropperSelection | minInset, maxInset | "auto" | | CropperSelection | resizeAroundCenter, zoomAroundCenter | false | | CropperSelection | borderRadius | "" | | CropperShade | borderRadius | Follows the selection when connected to one |

Insets constrain distances to the parent edges using CSS inset syntax: pixels, percentages, calc(), or auto for no limit. Set minInset="0" to keep an element inside its parent or maxInset="0" to require full coverage. Changes outside these limits are rejected. Use bounded to constrain the selection to the image rectangle instead.

initialCoverage uses image bounds when available and preserves explicit selection dimensions, so initialization may finish after loading.

<CropperCanvas background style={{ height: 400 }}>
  <CropperImage src="/photo.jpg" scalable translatable zoomAroundCenter />
  <CropperShade />
  <CropperSelection
    initialCoverage={0.5}
    aspectRatio={1}
    minInset="0"
    borderRadius="50%"
    movable
    resizable
    resizeAroundCenter
    zoomable
    zoomAroundCenter
  >
    <CropperHandle action="move" />
    <CropperHandle action="se-resize" />
  </CropperSelection>
</CropperCanvas>

borderRadius clips the selection and its $toCanvas() output. The shade and viewer follow its radius. Export as PNG or WebP to preserve transparent corners.

Image Loading and Previews

For image sources supplied after mount, render CropperViewer after the image's onReady callback fires. Readiness runs again when src or srcSet changes; pending callbacks are canceled on unmount.

Changing a viewer's selection or resize prop reconnects its element and updates the ref. Viewers also work with non-interactive images and retain the accepted crop when a change is canceled.

Keep the same CropperImage element when changing source or fit props. Changing only its React key can leave exports attached to the previous element. If replacing it, remount the canvas and its children together.

Typed Events

Image and selection onChange handlers expose typed x, y, width, and height fields. Call event.preventDefault() to reject a pending change.

Action events include pointer coordinates, scaling, rotation, and transform centers:

import type { CropperActionEvent } from "cropperjs-react-wrapper";

const handleAction = (event: CropperActionEvent) => {
  const { action, scale, centerX, centerY } = event.detail;
  if (action === "scale") {
    console.log({ scale, centerX, centerY });
  }
};

<CropperCanvas onAction={handleAction}>{/* ... */}</CropperCanvas>;

The package exports action, action-start, action-move, action-end, image-change, and selection-change event types and their detail types.

Development

Use the Node.js version in .node-version and npm version in package.json under packageManager, then run npm ci.

Commands

  • npm run dev / npm run dev:vite: Start the Vite demo.
  • npm run dev:nextjs: Build the library and start the Next.js example.
  • npm run build / npm run build:examples: Build the library alone or with all examples.
  • npm test / npm run test:all: Watch library tests or run all unit tests once.
  • npm run test:browser / npm run test:browser:firefox: Test all apps in Chromium or Firefox. Run npx playwright install chromium firefox and npm run build:examples first.
  • npm run typecheck: Typecheck the library and workspaces.
  • npm run lint: Check formatting and lint rules with Biome.

Examples

  • example/vite: Interactive demo.
  • example/react18: React 18 compatibility fixture.
  • example/nextjs: Next.js App Router fixture.

License

MIT