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.
| Prop | Type | Default | Description |
|---|---|---|---|
src | Signal<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. |
open | Signal<boolean> | boolean | false | Whether 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. |
id | string | — | Set on the file input, so a trigger's `for` reaches it. |
inputProps | ElementProps<"input"> | — | Props for the hidden file input. |
| Data attribute | Value |
|---|---|
[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 attribute | Value |
|---|---|
[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.
| Prop | Type | Default | Description |
|---|---|---|---|
aspect | number | 1 | Width 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. |
zoom | Signal<number> | number | 1 | How far in the picture is zoomed. 1 just covers the crop area. |
onZoomChange | (zoom: number) => void | — | Runs whenever the zoom changes. |
minZoom | number | 1 | The lowest zoom. |
maxZoom | number | 3 | The highest zoom. |
alt | string | "" | Alt text for the picture. |
| Data attribute | Value |
|---|---|
[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 attribute | Value |
|---|---|
[data-image-cropper-crop] | Present |
ImageCropperCancel
Throws the picture away and closes the dialog. Renders a Button; extra props are forwarded onto it.
| Data attribute | Value |
|---|---|
[data-image-cropper-cancel] | Present |