Image cropper
A fixed frame — square, round, 9:16, a banner — over a picture or a video the person drags and zooms; a focus point and a zoom out, cropRect for the pixels.
Web only — React, from @krizaka/ui/image-cropper. Beta: its API may still change in a minor version.
When to use
- To frame a profile picture or a cover before sending it.
- To choose what a vertical (9:16) or square version of a landscape video keeps.
When not to use
- To cut a video in time (not in space): the video trimmer.Use instead: Video trimmer
- To send a file as it is: the file upload.Use instead: File upload
Installation
Install
npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcssStyles
@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";Import
import { ImageCropper, cropRect } from "@krizaka/ui/image-cropper";Examples
Profile picture
A round mask on a square frame.
Drag or use the arrow keys to move the picture, + and − to zoom.Banner
A 3:1 frame for a profile's cover, zoomed in.
Drag or use the arrow keys to move the picture, + and − to zoom.Vertical version of a video
A <video> as the media, a 9:16 frame: choose what the vertical cut keeps.
Props
Chooses what a fixed frame keeps of a picture or a video: drag, zoom, keyboard; a focus point and a zoom out.
| Prop | Type | Default | Description |
|---|---|---|---|
aspectrequired | number | — | The frame's width / height: 1 (a square), 9 / 16 (vertical), 3 (a banner). |
alt | string | — | The picture's alternative text, passed translated (empty when the frame's name says enough). |
children | ReactElement<{ className?: string; style?: CSSProperties; }, string | JSXElementConstructor<any>> | undefined | — | A media element instead of src — a <video> to choose the frame of a clip. Its natural size is in naturalSize. |
className | string | — | Classes merged on the root. |
defaultValue | CropValue | { x: 0.5, y: 0.5, zoom: 1 } | The crop at first, uncontrolled. Default: centred, no zoom. |
labels | Partial<ImageCropperLabels> | — | The words, passed translated; English by default. |
maxZoom | number | 4 | The largest zoom. Default 4. |
naturalSize | { width: number; height: number; } | — | The source's size when children is a video: { width: video.videoWidth, height: video.videoHeight }. |
onValueChange | ((value: CropValue) => void) | — | Called on every move. |
round | boolean | — | A round mask over the square frame (a profile picture). |
showZoom | boolean | true | Shows the zoom slider under the frame. Default true. |
src | string | — | The picture to crop. Or children: a <video> (with the class it is given through mediaClassName). |
value | CropValue | — | The crop (controlled). |
Accessibility
- The frame is a focusable
groupnamed bylabels.frameand described bylabels.instructions. - The zoom is a
sliderread as a percentage. - Nothing moves but what the person moves.
Keyboard
| Keys | Action |
|---|---|
| Arrow keys | Move the picture in the frame (Shift: faster). |
| + / − | Zoom in or out. |
Best practices
- Store the focus point and the zoom (screen-independent), and crop on the server with
cropRect. - Use
roundfor an avatar: the person sees what others will see. - Keep the zoom slider (
showZoom): pinch and Ctrl + wheel are not obvious to everyone.
Related components
Generated from the code of @krizaka/ui 2.4.0: its meta.ts, its examples and its types.Edit this documentation on GitHub
File upload
A drop zone that checks type, size and count, a list of uploads with preview, progress, speed and the actions each state allows, and a queue that pauses and resumes — Tus-ready without depending on it.
Media capture
The camera in the page: a photo or a clip, front or back, the permission asked only on a gesture, and a way out every time the camera cannot start.