Sections

Components

Utilities

Forms

Hooks

useIsMobile

Image Cropper

Copy Markdown

Crop and transform images.

Docs API

PreviewCode

Installation#

CLIManual

pnpmbunnpmyarn

pnpm dlx shadcn@latest add @shark/image-cropper

Anatomy#

ImageCropper
├── ImageCropperImage
├── ImageCropperSelection
├── ImageCropperHandle
└── ImageCropperGrid

Usage#

import {
  ImageCropper,
  ImageCropperImage,
  ImageCropperSelection,
} from "@/components/ui/image-cropper";

<ImageCropper>
  <ImageCropperImage alt="Crop me" src="/image.jpg" />
  <ImageCropperSelection />
</ImageCropper>

Examples#

Aspect ratio#

Use the aspectRatio to lock the crop area to a specific aspect ratio.

PreviewCode

Circle crop#

Use cropShape="circle" for profile pictures or avatars.

PreviewCode

Initial crop#

Start with a pre-defined crop area using the initialCrop prop.

PreviewCode

Controlled zoom#

Control zoom programmatically with the zoom and onZoomChange props.

PreviewCode

Zoom limits#

Set minZoom and maxZoom to constrain how far users can zoom.

PreviewCode

Min and max size#

Constrain the crop area size with minWidth, minHeight, maxWidth, and maxHeight.

PreviewCode

Fixed crop area#

Set fixedCropArea to true when the crop area should stay fixed while the image moves underneath.

PreviewCode

API Reference#

ImageCropper#

Root wrapper. Manages crop state and handles.

Prop	Type	Default
`aspectRatio`	`number`	-
`cropShape`	`"circle"	"rectangle"`
`fixedCropArea`	`boolean`	`false`
`initialCrop`	`{ x: number; y: number; width: number; height: number }`	-
`maxHeight`	`number`	`Infinity`
`maxWidth`	`number`	`Infinity`
`maxZoom`	`number`	`5`
`minHeight`	`number`	`40`
`minWidth`	`number`	`40`
`minZoom`	`number`	`1`
`onCropChange`	`(details: CropChangeDetails) => void`	-
`onZoomChange`	`(details: ZoomChangeDetails) => void`	-
`rotation`	`number`	-
`zoom`	`number`	-
`className`	`string`	-

Attribute	Default
`--cropper-accent`	`var(--color-white)`
`--cropper-handler-size`	`--spacing(2)`
`--cropper-handler-width`	`--spacing(1)`

ImageCropperImage#

Image to crop. Pass src and alt.

Prop	Type	Default
`alt`	`string`	-
`src`	`string`	-
`className`	`string`	-

ImageCropperSelection#

Crop selection overlay with resize handles and optional grid.

Prop	Type	Default
`axis`	`"horizontal"	"vertical"
`className`	`string`	-

For a complete list of props, see the Ark UI documentation.

[

Hover Card ](/docs/components/hover-card)[

Input Group ](/docs/components/input-group)

On This Page

Installation Anatomy Usage Examples Aspect ratio Circle crop Initial crop Controlled zoom Zoom limits Min and max size Fixed crop area API Reference ImageCropper ImageCropperImage ImageCropperSelection