Skip to contentKino
Skip to Content

Image cropper

Picking the part of an image to keep, by pointer, touch, wheel and keyboard, with a set shape, a circle or a free one. Saving cuts the crop out of the file.

npx shadcn add https://kinoui.com/r/image-cropper.json
Share on

Examples

Cover image

Shown across the top of the Lisbon offsite project.

Shape

Drag or use the arrow keys to move the image, pinch or press plus and minus to zoom, and press R to rotate, or Shift and R to rotate back.

 

Default

The image pans and zooms under a still frame. Pick a shape, and save the crop from onValueCommitted.

Cover image

Shown across the top of the Lisbon offsite project.

Shape

Drag or use the arrow keys to move the selection, drag its edges, hold Alt with the arrow keys or press plus and minus to resize it, and press R to rotate, or Shift and R to rotate back.

 

Box

With mode="box" the image stays still and a selection moves over it: drag its edges to resize it, or drag outside it to draw a new one.

Cover image

Shown across the top of the Lisbon offsite project.

Shape

Drag or use the arrow keys to move the image, drag the edges of the crop or hold Alt with the arrow keys to resize it, pinch or press plus and minus to zoom, and press R to rotate, or Shift and R to rotate back.

 

Settle

With mode="settle" you resize the selection over the image, and when you let go it glides back to fill the area while the image zooms to match.

Drag or use the arrow keys to move the image, pinch or press plus and minus to zoom, and press R to rotate, or Shift and R to rotate back.

Position
–
Size
–
Rotation
–

Controlled

Hold the crop with value and onValueChange. It is null until there is one: the cropper then starts from the largest crop it can and reports it.

Profile photo

Shown next to your comments, on issues you own and in the people list.

RM
Rafael Morenorafael@kinoui.com

Circle

With shape="circle" the crop is round, and cropImage saves it as a PNG with clear corners.

Installation

npx shadcn@latest add https://kinoui.com/r/image-cropper.json
Files
lib/refs.tslib/reduce-motion.tslib/resize.tslib/swap.tsxcomponents/kino/spinner.tsxcomponents/kino/button.tsxlib/track.tslib/number-format.tscomponents/kino/slider.tsxlib/announce.tsxlib/run-progress.tslib/highlight.tscomponents/kino/image-cropper.tsx
Packages
@base-ui/reactclass-variance-authority

New to Kino? Installation covers what your project needs first and the @kino namespace.

API reference

ImageCropper

PropTypeDefaultDescription
srcstringNoneThe image: a URL, or an object URL for a file a person picked.
altstringNoneWhat the image shows.
crossOrigin'anonymous''use-credentials'NoneFor an image on another origin, so cropImage can read it from the same URL.
valueCropnullNoneThe crop, when you hold it: { x: number; y: number; width: number; height: number; rotation: 0 | 90 | 180 | 270 } in the pixels of the image as it shows after its turn. null until there is one.
defaultValueCropNoneThe crop it starts from. Left out, it starts from the largest crop the shape allows.
onValueChange(value: Crop, details: { reason: CropChangeReason }) => voidNoneCalled as the crop changes, on every frame of a drag. The reason is load, drag, resize, draw, pinch, wheel, keyboard, zoom, rotate, aspect or cancel.
onValueCommitted(value: Crop) => voidNoneCalled once a change is done: on letting go, after a key, and once the wheel rests. Save the crop here.
aspectRationumberNoneWidth over height, such as 1 or 16 / 9. Left out, the shape is free.
shape'rectangle''circle''rectangle'A circle is always as wide as it is high.
maxZoomnumber3How far it zooms in: 3 shows a third of the width of the largest crop.
disabledbooleanfalseWhether the crop can change.

ImageCropperArea

PropTypeDefaultDescription
mode'frame''box''settle''frame'What a person moves: frame pans and zooms the image under a still frame, box moves and resizes a selection over a still image, and settle resizes the selection, then glides it back to fill the area.
aria-labelstring'Crop area'What a screen reader calls it, such as “Profile photo”.

cropImage

PropTypeDefaultDescription
typestringNoneThe file type, such as image/webp. A circle is a PNG, so its corners stay clear; anything else a JPEG.
qualitynumber0.92From 0 to 1, for JPEG and WebP.
maxWidthnumberNoneThe widest it may be, in px.
maxHeightnumberNoneThe tallest it may be, in px.
shape'rectangle''circle''rectangle'circle keeps only the round part.
backgroundstring'#fff'What shows through a transparent image in a JPEG.

Data attributes

AttributeOnDescription
data-modeImageCropperAreaframe, box or settle.
data-interactingImageCropperAreaPresent while a pointer moves, resizes or zooms the crop. The thirds show.
data-followingImageCropperAreaPresent while the crop follows a pointer, the wheel or the zoom thumb, so it moves at once instead of gliding.
data-disabledImageCropper, ImageCropperAreaPresent when it is disabled.

Accessibility

  • The area is one stop in the tab order. Arrow keys move the crop (with Shift, further), plus and minus zoom, R turns the image and Shift and R turns it back. In box and settle, Alt and the arrows resize the selection. Escape cancels a drag.
  • The area is an application, so a screen reader in browse mode passes its keys on. Its instructions are its description.
  • The crop is announced in words once a key is let go, and every zoom, turn and load error is announced in a status region.
  • The zoom has a Slider and two buttons, and the turn a button, so nothing needs a pointer, a wheel or two fingers.
  • The wheel zooms only once the area has focus, or with Ctrl or Cmd held, so it never takes over the page’s scrolling.