React Image Cropper

A simple, composable, headless React component for interactive image cropping — inspired by the experience on X.

Features

• Headless & Composable: Provides building blocks (Cropper.Root, Cropper.Image, Cropper.CropArea, Cropper.Description) for full control over structure and styling.
• Interactive: Supports zooming (mouse wheel, pinch gesture) and panning (mouse drag, touch drag, arrow keys).
• Aspect Ratio: Enforces a specified aspect ratio for the crop area.
• Controlled/Uncontrolled: Manage zoom state internally or control it via props.
• Crop Calculation: Outputs precise pixel coordinates of the cropped area relative to the original image.
• Accessible: Designed with ARIA attributes and requires a description element for screen reader users.
• Customizable: Control zoom limits, sensitivity, padding, keyboard steps, and apply custom styles.

Installation

npm install @origin/image-cropper
# or
yarn add @origin/image-cropper
# or
pnpm add @origin/image-cropper

Usage

Here's a basic example of how to use the Cropper primitive components:

import { Cropper } from "@origin-space/image-cropper"
import React from "react"

function MyImageCropper() {
  const [cropData, setCropData] = React.useState<Area | null>(null)

  return (
    <div>
      <Cropper.Root
        image="https://images.unsplash.com/photo-1494790108377-be9c29b29330"
        aspectRatio={1}
        onCropChange={setCropData}
        className="relative flex h-80 w-full cursor-move touch-none items-center justify-center overflow-hidden rounded-md border focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
      >
        {/* Required for accessibility */}
        <Cropper.Description className="sr-only" />
        <Cropper.Image className="pointer-events-none h-full w-full select-none object-cover" />
        <Cropper.CropArea className="pointer-events-none absolute border-2 border-dashed border-background shadow-[0_0_0_9999px_rgba(0,0,0,0.6)]" />
      </Cropper.Root>

      {cropData && (
        <pre className="mt-4 overflow-auto rounded bg-muted p-2 text-sm">
          {JSON.stringify(cropData, null, 2)}
        </pre>
      )}
    </div>
  )
}

For more examples and integration with UI frameworks, check out the implementation on Origin UI.

Origin UI Abstraction

Origin UI provides a pre-styled component built on top of @origin-space/image-cropper. If you're using Origin UI or want a quicker setup, you can use this abstraction.

Usage with Abstraction

Using the Origin UI abstraction simplifies the markup:

"use client"

import React from "react"
import {
  Cropper,
  CropperCropArea,
  CropperDescription,
  CropperImage,
} from "@/registry/default/ui/cropper"

type Area = { x: number; y: number; width: number; height: number }

export default function Component() {
  const [cropData, setCropData] = React.useState<Area | null>(null)

  return (
    <div className="flex flex-col gap-4">
      <Cropper
        className="h-80"
        image="https://images.unsplash.com/photo-1494790108377-be9c29b29330"
        aspectRatio={1}
        onCropChange={setCropData}
      >
        <CropperDescription />
        <CropperImage />
        <CropperCropArea />
      </Cropper>

      {cropData && (
        <pre className="overflow-auto rounded bg-muted p-2 text-sm">
          {JSON.stringify(cropData, null, 2)}
        </pre>
      )}
    </div>
  )
}

Components

• Cropper.Root: The main container and controller. It handles logic, state, and interactions.
• Cropper.Image: Renders the actual <img> tag. It's positioned and scaled by Cropper.Root.
• Cropper.CropArea: A simple <div> representing the visual crop area. You style this component to show the bounds.
• Cropper.Description: Renders a <div> intended for accessibility instructions. Its id is automatically linked via aria-describedby on the Root element. This component is required for accessibility.

Cropper.Root Props

Prop	Type	Default	Description
image	string	Required	URL of the image to crop.
children	React.ReactNode	Required	Should include Cropper.Image, Cropper.CropArea, and Cropper.Description.
aspectRatio	number	1	The desired width/height aspect ratio (e.g., 1, 1.5, 4 / 3, 16 / 9).
cropPadding	number	25	Minimum padding (in pixels) between the crop area edges and the container edges.
minZoom	number	1	Minimum zoom level (1 = 100% original size relative to crop area).
maxZoom	number	3	Maximum zoom level.
zoomSensitivity	number	0.005	Multiplier for mouse wheel delta to control zoom speed.
keyboardStep	number	10	Number of pixels to pan the image when using arrow keys.
zoom	number	undefined	Controlled zoom level. If provided, component zoom state is controlled externally.
onCropChange	(pixels: Area | null) => void	undefined	Callback function triggered whenever the crop area changes. Receives pixel data or null if invalid.
onZoomChange	(zoom: number) => void	undefined	Callback function triggered when the zoom level changes interactively. Essential for controlled zoom prop.
className	string	undefined	CSS class for the root container element.
style	React.CSSProperties	undefined	Inline styles for the root container element.
...restProps			Any other standard HTMLDivElement props are passed to the root container.

onCropChange Data (Area)

The Area object received by onCropChange contains the following properties relative to the original image dimensions:

• x: The x-coordinate of the top-left corner of the cropped area.
• y: The y-coordinate of the top-left corner of the cropped area.
• width: The width of the cropped area in pixels.
• height: The height of the cropped area in pixels.

Accessibility

It is crucial to include a Cropper.Description component within Cropper.Root. This provides necessary context for screen reader users about how to interact with the cropper. If you don't provide one, a warning will appear in the console. You can visually hide the description using standard CSS techniques (e.g., an sr-only class).

Styling

The component is headless, meaning it doesn't come with built-in styles beyond basic positioning for the image. You are expected to style the Cropper.Root, Cropper.Image, and especially the Cropper.CropArea using CSS classes (className) or inline styles (style) to match your application's design. The Cropper.CropArea typically needs styling to appear as an overlay (e.g., border, semi-transparent background outside the area).

License

MIT