Image Cropper React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Image Cropper is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import ImageCropper from @/components/ui/image-cropper.

import { useState } from "react"
import { Button } from "@/components/ui/button"
import { ImageCropper, type ImageCropperApi } from "@/components/ui/image-cropper"

export function ListingPhoto({ onSave }: { onSave: (file: Blob) => void }) {
  const [api, setApi] = useState<ImageCropperApi | null>(null)
  const [saving, setSaving] = useState(false)

  const crop = async () => {
    if (!api) return
    setSaving(true)
    try {
      onSave(await api.toBlob({ type: "image/jpeg", quality: 0.9, maxSize: 1600 }))
    } finally {
      setSaving(false)
    }
  }

  return (
    <div className="flex max-w-xl flex-col gap-4">
      <ImageCropper
        src="/demo/apartment.jpg"
        defaultAspect={4 / 3}
        setApi={setApi}
        labels={{
          aspect: "Ratio",
          hint: "Drag to move, scroll to zoom",
          touchHint: "Drag to move, pinch to zoom",
        }}
      />
      <Button loading={saving} onClick={crop}>
        Crop
      </Button>
    </div>
  )
}

Props

• src*
  string | Blob | File

  The photo: a URL, a data URL or a File / Blob from an input (its object URL is created and revoked for you). Modern browsers apply EXIF orientation to both the preview and the export.

• value
  CropValue ({ area: CropArea; zoom: number; rotation: number; aspect: number | null; flipH?: boolean })

  The controlled crop. area is { x, y, width, height } in source pixels of the rotated photo. A value from outside that differs from the last one reported restores that exact crop.

• defaultValue
  CropValue

  The uncontrolled start, for example a crop saved earlier. Without it the frame starts centered at the largest area of the ratio.

• onValueChange
  (value: CropValue) => void

  Fires when an interaction ends (a drag, a pinch, the wheel settling, a slider released, a key released, a tween finished), never per frame. Also once when the photo is ready, with the starting crop.

• onCropChange
  (value: CropValue) => void

  Every frame while the crop moves. Rarely needed; prefer onValueChange.

• aspect
  number | null

  The controlled ratio (width / height). null is a free crop that starts at the photo's own ratio and has corner handles.

• defaultAspectdefault "null"
  number | null

  The uncontrolled starting ratio, e.g. 4 / 3 for a listing photo.

• onAspectChange
  (aspect: number | null) => void

  A ratio was picked from the presets.

• aspectPresetsdefault "DEFAULT_ASPECT_PRESETS"
  AspectPreset[] | false ({ key: string; label: ReactNode; value: number | null; icon?: ReactNode })

  The ratios offered: Free, 1:1, 4:3, 3:4, 16:9, 9:16 by default, each with a small outline of its shape. false hides the picker (a fixed ratio). The default Free label follows labels.free. Exported as DEFAULT_ASPECT_PRESETS, so you can spread it and add your own.

• cropShapedefault "rect"
  "rect" | "round"

  round draws a circular frame for avatars and logos, forces the ratio to 1 and hides the presets; the export masks the circle.

• showGriddefault "interacting"
  "always" | "interacting" | "never"

  The rule-of-thirds grid inside the frame. interacting fades it in while you drag, pinch, zoom or rotate.

• minZoomdefault 1
  number

  The smallest zoom. At 1 the photo just fits the stage. With a resized free frame the zoom also stops where the photo would stop covering it.

• maxZoomdefault 4
  number

  The largest zoom for the slider, the buttons, the wheel and pinch.

• zoomStepdefault 0.1
  number

  The slider step and the + / − key step. The zoom buttons move five steps with a short glide.

• rotatabledefault true
  boolean

  Shows the rotation row: a 90° left turn and a fine slider from −45° to 45° with a center mark.

• flippabledefault false
  boolean

  Adds a horizontal flip button (and the f key). The export mirrors the photo too.

• restrictPositiondefault true
  boolean

  Keeps the photo covering the whole frame. Off, the photo can move past the frame and the uncovered part exports as the background.

• objectFitdefault "contain"
  "contain" | "cover"

  How the photo sits in the stage at zoom 1: contain shows all of it, cover fills the stage.

• heightdefault 360
  number

  The stage height in px. Phones cap it at 60dvh so the toolbar stays on screen.

• toolbardefault true
  boolean

  The controls under the stage. Off, the photo still moves, pinches, zooms with the wheel and answers the keys; drive the rest through setApi.

• exportdefault "{ type: "image/jpeg", quality: 0.9, maxSize: 2048 }"
  CropExportOptions ({ type?: ImageType; quality?: number; maxSize?: number; width?: number; height?: number; background?: string; round?: boolean })

  Defaults for toBlob / toCanvas. maxSize caps the longest side (never upscales), width / height set an exact size, round masks a circle (on by default for a round crop), background fills behind (JPEG gets white). cropImage (see Parts) runs the same export without the component.

• overlayColordefault "rgba(0, 0, 0, 0.55)"
  string

  The dim outside the frame. Any CSS color.

• sizedefault "md"
  "sm" | "md"

  The toolbar controls: sm 32px buttons and slim sliders, md 40px (44px on touch).

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The slider fills, the selected ratio chip and the segmented thumb.

• colordefault ""
  string

  Any CSS color; replaces the tone for the sliders and the selected ratio.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg"

  The stage corners: 0 / 12 / 16 / 24px.

• disableddefault false
  boolean

  Dims the stage and the toolbar and ignores every gesture and key.

• setApi
  (api: ImageCropperApi) => void

  Receives { toBlob(options?), toCanvas(options?), reset(), rotateBy(degrees), zoomTo(zoom) } after mount. toBlob rejects with labels.corsError when a remote photo has no CORS headers (the preview still works).

• onError
  (error: Error) => void

  The photo failed to load, or an export failed. Load errors also show a retry on the stage for URLs.

• labelsdefault "DEFAULT_IMAGE_CROPPER_LABELS"
  Partial<ImageCropperLabels>

  Every string: aspect, free, zoom, zoomIn, zoomOut, rotate, rotateLeft, flip, reset, area (the frame's name for screen readers), loading, error, retry, hint, touchHint, corsError, exportError, and the announcements aspectChanged(label), rotated(degrees, formatted), flipped, resetDone. English defaults in DEFAULT_IMAGE_CROPPER_LABELS.

• classNames
  Partial<Record<"stage" | "area" | "grid" | "handle" | "toolbar" | "aspects" | "zoom" | "rotate" | "reset" | "pill", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

Used in

More React media components