Image Cropper
Image cropping: pan, zoom, rotate, aspect ratios and a round avatar. Pro · Forms and input › Files and images
Crop an image to a fixed aspect: pan by dragging (or arrow keys), zoom with the slider, wheel, pinch or +/-, rotate in 90° steps. Reports the crop area for getCroppedBlob.
Installation
npx valyro-cli@latest login
npx valyro-cli@latest add image-croppernpm install valyro-ui-pro
import 'valyro-ui-pro/styles.css';
import { ImageCropper } from 'valyro-ui-pro';Props
| Prop | Type | Default | |
|---|---|---|---|
src | string | null | Image URL (an object URL or data URL works without CORS). Nothing is shown while empty. | |
alt | string | '' | Alt text of the image being cropped; empty marks it decorative. |
aspect | number | 1 | Width / height of the crop (default 1). |
shape | 'rect' | 'circle' | 'rect' | circle for avatars: the crop is still a square area; mask the result with getCroppedBlob(…, { shape: 'circle' }). |
zoom | number | Controlled zoom; use with onZoomChange. | |
defaultZoom | number | 1 | Initial zoom when uncontrolled. |
onZoomChange | (zoom: number) => void | Called with the new zoom when it changes. | |
minZoom | number | 1 | Lowest zoom of the slider, wheel and pinch; 1 is the image just covering the crop frame. |
maxZoom | number | 4 | Highest zoom of the slider, wheel and pinch, relative to the image just covering the crop frame. |
rotation | number | Degrees, clockwise. | |
defaultRotation | number | 0 | Initial rotation when uncontrolled. |
onRotationChange | (rotation: number) => void | Called with the new rotation when it changes. | |
grid | boolean | 'interaction' | 'interaction' | Rule-of-thirds grid: always, never, or while moving the image (default). |
height | number | string | 320 | Height of the crop stage (default 320px). |
controls | boolean | true | Zoom slider and rotate button under the image (default true). |
onCropChange | (area: CropArea, percent: CropArea) => void | Every change of the crop, while it happens. | |
onCropComplete | (area: CropArea, percent: CropArea) => void | The crop after an interaction ends (and once the image loads): area in px of the rotated image, and in percent. | |
labels | Partial<ImageCropperLabels> | Overrides for the built-in English text; keys left out keep their defaults. |
Related components
- File Uploader — File uploads
- Text Input — Text fields
- Textarea — Multiline text input
- Search Input — Search field
- Mentions Input — Text with @mentions and #tags, async suggestions
- Tags Input — Tag entry
- Select — Pick one option from a list
- Multi Select — Pick several options
- Combobox — Searchable select
- Listbox — Option list on the page: one or several, Shift ranges
- Chip Group — Chip group with icons: one or several options
- Checkbox Tree — Checkbox tree: cascading, indeterminate state, keyboard
Previous: File Uploader · Next: Form Field · All Forms and input