implement
Image Cropper

Image Cropper

Choose an image, then move and zoom it under a fixed crop area.

import { Div, signal } from "@implementjs/core";
import {
	ImageCropper,
	ImageCropperCancel,
	ImageCropperControls,
	ImageCropperCrop,
	ImageCropperCropper,
	ImageCropperDialog,
	ImageCropperPreview,
	ImageCropperTrigger,
} from "@/lib/components/ui/image-cropper";

export default function ImageCropperDemo() {
	const src = signal("https://github.com/ieedan.png");

	return Div(
		{ class: "flex justify-center" },
		ImageCropper(
			{ src },
			ImageCropperTrigger(ImageCropperPreview()),
			ImageCropperDialog(
				ImageCropperCropper(),
				ImageCropperControls(ImageCropperCrop(), ImageCropperCancel()),
			),
		),
	);
}

An image cropper takes a file, lets you pan and zoom it under a fixed crop area, and hands back the part inside as a new image. The root keeps the state and one hidden file input; a trigger is a label pointing at it, so anything can open the file picker. The picture is cropped to a PNG and returned as an object URL, which the root writes to src.

import {
	ImageCropper,
	ImageCropperCancel,
	ImageCropperCrop,
	ImageCropperCropper,
	ImageCropperTrigger,
} from "@implementjs/primitives";

const src = signal("");

ImageCropper(
	{ src },
	ImageCropperTrigger("Choose a picture"),
	// put the cropper wherever it should show — a dialog, a page — when `open` is true
	Div(
		ImageCropperCropper({ aspect: 1, style: { width: "300px", height: "300px" } }),
		ImageCropperCrop("Crop"),
		ImageCropperCancel("Cancel"),
	),
);

Each part accepts optional props and children — pass a props object when you need attributes, or pass children directly. See createComponent.

Open state

There is no dialog in the primitive: it keeps an open signal and sets it when a file is chosen, and you show the cropper however you like. Pass a signal to read it or to close the cropper from outside. ImageCropperContext.Use hands you the whole state — open, src, and tempUrl, the picture being cropped — which is how the styled version binds a dialog to it:

ImageCropperContext.Use((state) => Dialog({ open: state.open } /* cropper and buttons */));

Moving and zooming

The picture starts covering the crop area, so the saved image never has empty edges. Drag to pan, scroll or pinch to zoom; with focus on the surface, the arrow keys pan and + and - zoom. zoom takes a number or a signal — bind it to a slider — between minZoom and maxZoom.

aspect is width over height of the area that is kept. shape sets data-shape to "round" or "rect" for styling the outline; the saved image is always a rectangle, so round it with CSS wherever you show it.

The surface has no size of its own, so give it a width and a height. Style the dimmed surround through the crop area, [data-image-cropper-area], which sits over the picture and is sized to the kept region.

Files

Only images a browser can draw are accepted (VALID_IMAGE_TYPES); anything else calls onUnsupportedFile and nothing opens. The same file can be chosen twice in a row. Every object URL created is revoked when the root unmounts, so copy the picture out — getFileFromUrl(url) turns it into a File for uploading — before then.

API Reference

ImageCropper

The root. It renders no element of its own — only the hidden file input every trigger points at — and holds the picture, the crop, and the open state.

PropTypeDefaultDescription
srcSignal<string> | string""The current image URL. A confirmed crop writes its object URL here; pass a signal to read it.
onSrcChange(src: string) => void—Runs whenever the image URL changes.
onCropped(url: string) => void—Runs with the object URL of the cropped image once a crop is confirmed.
onUnsupportedFile(file: File) => void—Runs when the chosen file is not an image a browser can draw.
openSignal<boolean> | booleanfalseWhether the crop dialog is open. It opens itself when a file is chosen; pass a signal to control it.
onOpenChange(open: boolean) => void—Runs whenever the open state changes.
idstring—Set on the file input, so a trigger's `for` reaches it.
inputPropsElementProps<"input">—Props for the hidden file input.
Data attributeValue
[data-image-cropper-input]Present, on the file input

ImageCropperTrigger

A label for the file input. Clicking anything inside it opens the file picker. Renders a Label; extra props are forwarded onto it.

Data attributeValue
[data-image-cropper-trigger]Present

ImageCropperCropper

The surface the picture is moved and zoomed on under a fixed crop area. Drag to pan, scroll or pinch to zoom; with focus, arrow keys pan and + / - zoom. It has no size of its own, so give it a width and a height. Renders a Div; extra props are forwarded onto it.

PropTypeDefaultDescription
aspectnumber1Width over height of the area that is kept.
shape"round" | "rect""round"Sets data-shape on the surface and the area, so the outline can be styled. The saved image is always a rectangle.
zoomSignal<number> | number1How far in the picture is zoomed. 1 just covers the crop area.
onZoomChange(zoom: number) => void—Runs whenever the zoom changes.
minZoomnumber1The lowest zoom.
maxZoomnumber3The highest zoom.
altstring""Alt text for the picture.
Data attributeValue
[data-image-cropper-cropper]Present
[data-image-cropper-area]Present, on the crop area inside
[data-shape]"round" | "rect"

ImageCropperCrop

Confirms the crop: the picture becomes the root's src and the dialog closes. Renders a Button; extra props are forwarded onto it.

Data attributeValue
[data-image-cropper-crop]Present

ImageCropperCancel

Throws the picture away and closes the dialog. Renders a Button; extra props are forwarded onto it.

Data attributeValue
[data-image-cropper-cancel]Present