Documentation
Asgard
Getting started
Theming
Guides
Inputs & forms
Pickers
Data display
Layout & docking
Feedback & overlays
Navigation & chrome
Inputs & forms
Crop, zoom and adjust an image on a canvas.
Canvas-based image cropping with interactive pan, zoom, rotation and a live crop overlay.
Key features:
cropShape:rectangleorcircle(ideal for avatars)- Preset and free aspect ratios (
1:1,16:9,free, …) - Rotation, flipping and brightness / contrast adjustments
- Undo / redo history and PNG / JPEG / WebP export
- Imperative
refAPI (getCroppedImage,rotate90,undo, …)
Loading preview…
When to use it
- Avatar and profile-photo editors
- Thumbnail and banner generators
- Any precise image selection before upload
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | File | HTMLImageElement | — | Image to crop. Accepts a URL, a File, or an existing image element. |
cropShape | 'rectangle' | 'circle' | 'rectangle' | Shape of the crop area. Circle is useful for profile photos. |
aspectRatio | 'free' | '1:1' | '3:4' | '4:3' | '16:9' | '21:9' | '9:16' | 'custom' | 'free' | Locks the crop to a ratio. Use free for unconstrained cropping. |
customAspectRatio | number | — | Ratio used when aspectRatio is "custom". |
showGrid | boolean | false | Show a rule-of-thirds grid overlay to aid composition. |
snapToGrid | boolean | false | Snap the crop edges to a pixel grid while dragging. |
gridSize | number | 10 | Grid spacing in pixels used for snapping. |
constrainToImage | boolean | false | Keep the crop region within the visible image bounds. |
allowRotation | boolean | false | Enable rotation controls (free + 90° increments). |
allowFlip | boolean | false | Enable horizontal and vertical flip controls. |
showImageAdjustments | boolean | false | Expose brightness and contrast sliders. |
enableHistory | boolean | false | Enable undo / redo across crop, transform and adjustment changes. |
minZoom | number | 0.1 | Minimum zoom factor. |
maxZoom | number | 5 | Maximum zoom factor. |
initialZoom | number | 1 | Zoom factor applied on load. |
semantic | 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info' | 'primary' | Accent color for the crop handles and border. |
backgroundColor | string | '#000000' | Fill for the area outside the image. |
exportTransparent | boolean | false | Export out-of-image areas as transparent (PNG only). |
onCropChange | (crop: CropArea) => void | — | Fired continuously as the crop region changes. |
onCropComplete | (image: CroppedImageData) => void | — | Fired with the cropped result after an export. |
onZoomChange | (zoom: number) => void | — | Fired when the zoom factor changes. |
onRotationChange | (rotation: number) => void | — | Fired when the rotation changes. |
Notes
- The ref exposes getCroppedImage, setZoom, setRotation, rotate90, flipHorizontal/Vertical, undo/redo, canUndo/canRedo and resetTransform.
- getCroppedImage resolves with { blob, dataUrl, dimensions, cropArea }. Output formats are png, jpeg and webp.
- enableHistory must be true for undo/redo to track crop, transform and adjustment changes.
- The component reads the canvas on mount, so it renders client-side only (it is excluded from server rendering in this explorer).
Presets