Cropper

The cropper lets users pan and zoom an image inside a fixed crop frame, then export the result. Use it for avatar uploads, cover images, and any flow that needs a constrained crop with optional aspect-ratio presets.

Preview

Installation

npx shadcn@latest add @cubby-ui/cropper

Usage


import {
  Cropper,
  CropperCropArea,
  CropperDescription,
  CropperImage,
} from "@/components/ui/cubby-ui/cropper";


<Cropper>
  <CropperDescription />
  <CropperImage />
  <CropperCropArea />
</Cropper>

Composition

Cropper holds the image and crop frame. The control components render alongside it and drive state through the useCropper hook.


Cropper
├── CropperImage
├── CropperCropArea | CropperCropAreaCircular
└── CropperDescription
 
CropperControls
├── CropperZoomControls
├── CropperAspectRatioControls
├── CropperInfo
└── CropperActions

Examples

Aspect Ratios

Pass aspectRatio to constrain the crop frame to a fixed ratio.

With Preview

Read onCropChange to render a live preview of the cropped result.

Download Cropped Image

Use createCropCanvas and downloadCroppedImage to export the crop as a file.

Pro Features

Combine aspect-ratio presets, circular crops, and custom dimensions for a full editor.

API Reference

The image surface (Cropper, CropperImage, CropperCropArea, CropperCropAreaCircular, CropperDescription) is built on top of @origin-space/image-cropper. Its props pass through to that library. The control parts (CropperControls, CropperZoomControls, CropperAspectRatioControls, CropperInfo, CropperActions) are custom, and useCropper wires them together.

Props

Pan-and-zoom image surface and crop frame. Wraps the cropper library's Root.

Prop

Type

Default

CropperZoomControls

Zoom out, zoom in, and optional reset buttons. Renders a custom toolbar.

Prop

Type

Default

CropperAspectRatioControls

Row of preset buttons for switching the crop ratio.

Prop

Type

Default

CropperInfo

Read-only summary of zoom, aspect, and crop size.

Prop

Type

Default

CropperActions

Optional download and export buttons.

Prop

Type

Default

Hooks

useCropper


function useCropper(options?: UseCropperOptions): {
  zoom: number;
  aspectRatio: number;
  cropData: CropData | undefined;
  setZoom: (zoom: number) => void;
  setAspectRatio: (ratio: number) => void;
  onCropChange: (cropArea: Area | null) => void;
  reset: () => void;
  exportCrop: (
    image: HTMLImageElement,
    filename?: string,
  ) => Promise<{ canvas: HTMLCanvasElement; blob: Blob; dataUrl: string } | null>;
  config: { minZoom: number; maxZoom: number; zoomStep: number };
};

Manages zoom, aspect ratio, and crop state for a Cropper, and wires up the control parts. Pass setZoom/zoom to CropperZoomControls, setAspectRatio/aspectRatio to CropperAspectRatioControls, and onCropChange to Cropper.

Options

Prop

Type

Default

Returns

Property	Type	Description
`zoom`	`number`	Current zoom level.
`aspectRatio`	`number`	Current aspect ratio.
`cropData`	`CropData \| undefined`	Latest crop metadata from `onCropChange`.
`setZoom`	`(zoom: number) => void`	Sets zoom, clamped to `minZoom`/`maxZoom`.
`setAspectRatio`	`(ratio: number) => void`	Sets the aspect ratio.
`onCropChange`	`(cropArea: Area \| null) => void`	Handler to pass to `Cropper`.
`reset`	`() => void`	Resets zoom and aspect ratio to their initial values.
`exportCrop`	`(image, filename?) => Promise<{ canvas; blob; dataUrl } \| null>`	Renders the current crop to a canvas, optionally downloading it.
`config`	`{ minZoom; maxZoom; zoomStep }`	Resolved zoom bounds and step.

Utilities

createCropCanvas


function createCropCanvas(
  image: HTMLImageElement,
  cropArea: Area,
  isCircular?: boolean,
): HTMLCanvasElement;

Draws the cropped region of image to a canvas. Pass isCircular to clip the output to a circle.

downloadCroppedImage


function downloadCroppedImage(canvas: HTMLCanvasElement, filename?: string): void;

Triggers a browser download of the canvas as a PNG. filename defaults to "cropped-image.png".

getCroppedImageBlob


function getCroppedImageBlob(canvas: HTMLCanvasElement): Promise<Blob>;

Resolves the canvas contents as a Blob, useful for uploading the crop.

Cropper

Aspect Ratio

Live Preview Cropper

Original Image

Aspect Ratio

Crop Preview

Export Options

Professional Image Cropper

Preset Selection

Export

On this page