implement
Image Cropper

Image Cropper

Upload an image, then crop it in a dialog.

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()),
			),
		),
	);
}

Installation

npx jsrepo add @implementjs/ui/image-cropper

It installs @implementjs/lucide at the same time, plus the avatar, button, and dialog components it is built from.

Usage

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

const src = signal("");

ImageCropper(
	{ src, onCropped: (url) => upload(url) },
	ImageCropperTrigger(ImageCropperPreview()),
	ImageCropperDialog(
		ImageCropperCropper(),
		ImageCropperControls(ImageCropperCrop(), ImageCropperCancel()),
	),
);

The composition:

ImageCropper
├── ImageCropperTrigger
│   └── ImageCropperPreview
└── ImageCropperDialog
    ├── ImageCropperCropper
    └── ImageCropperControls
        ├── ImageCropperCrop
        └── ImageCropperCancel

src is an object URL; to send it to a server, turn it into a file with getFileFromUrl(src).

Custom preview

Pass child to ImageCropperPreview to draw the picture yourself, and aspect and shape to the cropper to match:

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

export default function ImageCropperWideDemo() {
	const src = signal("");

	return Div(
		{ class: "flex justify-center" },
		ImageCropper(
			{ src },
			ImageCropperTrigger(
				ImageCropperPreview({
					child: (url) =>
						Div(
							{
								class:
									"flex aspect-video w-64 items-center justify-center overflow-hidden rounded-md border border-dashed bg-muted text-sm text-muted-foreground",
							},
							Span(
								{ class: url.bind((current) => (current === "" ? "" : "hidden")) },
								"Choose a cover image",
							),
							Img({
								src: url.bind((current) => current || undefined),
								alt: "Cover",
								class: url.bind((current) =>
									current === "" ? "hidden" : "size-full object-cover",
								),
							}),
						),
				}),
			),
			ImageCropperDialog(
				ImageCropperCropper({ aspect: 16 / 9, shape: "rect" }),
				ImageCropperControls(ImageCropperCrop(), ImageCropperCancel()),
			),
		),
	);
}

API Reference

Every prop the styling does not consume is forwarded to the Image Cropper primitive, so the tables below are the whole surface.

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 crop icon and a label unless you pass children of your own. 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 trash icon and a label unless you pass children of your own. Renders a Button; extra props are forwarded onto it.

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

ImageCropperPreview

What the trigger shows: the current src in a round avatar, with an upload icon until there is one. Every Avatar prop is forwarded. Renders a Div; extra props are forwarded onto it.

PropTypeDefaultDescription
child(src: Readable<string>) => Child—Draw the picture yourself instead of in an avatar. It is handed the current src.

ImageCropperDialog

The modal the picture is cropped in. It opens when a file is chosen and closes on crop or cancel. Every DialogContent prop is forwarded. Renders a Div; extra props are forwarded onto it.

ImageCropperControls

A centred row for the crop and cancel buttons. Renders a Div; extra props are forwarded onto it.