Cropper

Anatomy

Three parts. Cropper renders two boxes: an outer wrapper that takes your className and is size-full — so in a parent without a height it collapses to nothing — and inside it the interactive element, the one Tab reaches and every key and pointer event drives. CropperArea draws the frame and dims everything around it.

import { Cropper, CropperArea, CropperImage } from '@comitor/ui'

<Cropper                            // outer div gets className — it is size-full, so give it a height
  aspectRatio={1}                   // width ÷ height of the frame
  shape="circle"                    // rounds the frame only; the area you get back is still a square
  onCropAreaChange={(area, pixels) => …}
  className="min-h-72"
>                                   // inner div: role="application", tabIndex 0 — Tab reaches it, keys drive it
  <CropperImage src={src} alt="…" />  // or <CropperVideo src={src} />
  <CropperArea />                   // the frame and the dimmed surround — renders once the media has loaded
</Cropper>
// after the cropper element: hidden key instructions (aria-describedby) and a polite live region for zoom

Two coordinate systems come back out. crop is where the picture sits on screen, in CSS pixels from the centre — the same numbers point at a different part of the picture once the layout changes. croppedAreaPixels is the rectangle in the image’s own pixels, the only number worth saving or drawing; croppedArea is the same rectangle in percent.

A profile picture

aspectRatio={1} and shape="circle", with the zoom held in state so a Slider can drive it. The circle on the right is not a mock-up: every onCropAreaChange draws croppedAreaPixels from the real <img> onto a <canvas> with drawImage — the same pixels a save would upload. Drag, scroll, or focus the cropper and use the keys.

Xem trướcMã

Zoom1.00×

loading…

onCropComplete × 0

Two callbacks, two jobs. onCropAreaChange fires at most once per animation frame for any change — the first load, a drag in progress, a zoom set by the slider — so it suits a live preview and is the one to keep for Save. onCropComplete fires once when a gesture ends; the counter moves on release, on key-up and a quarter-second after a scroll, but never for the first load or a slider move. It is the place for expensive work. Notice too that this demo re-renders on every frame of a drag — exactly what used to snap an uncontrolled Dice UI cropper back to the centre.

A 16:9 cover

Project covers and workspace banners want a wide frame. aspectRatio can change while the cropper is mounted — the frame is recomputed and the picture clamped back inside it — and withGrid adds rule-of-thirds lines. The badge in the corner reads the cropper’s own state with useCropper; it renders inside the cropper, so it is aria-hidden.

Xem trướcMã

16:93:14:3

1.0×

croppedAreaPixels — loading…

If your server resizes images anyway, the rectangle is all it needs: post the original file with croppedAreaPixels and crop there, and the browser never re-encodes the picture.

The numbers, and the keyboard

Fully controlled: crop and zoom live in state, and Reset writes them back. Tab to the cropper and press → twenty times — crop.x moves 20 pixels, one per press (Shift moves 0.2). In Dice UI the same twenty presses moved the picture 1 pixel in total. + and - zoom around the centre in steps of 0.1, and each key-up closes the interaction, so the completion counter moves with you.

Xem trướcMã

crop

x 0.0 · y 0.0

zoom

1.50

area %

…

area px

…

complete

× 0

Reset

Crop first, then upload

ImageUploadField from @comitor/ui/uploader uploads the moment a file is chosen — there is no step in between to crop. A cropping flow is built one level down, on useFileUpload from the same entry: your own file input makes an object URL, the cropper shows it, and Save draws croppedAreaPixels onto a canvas, encodes it with toBlob, and hands the result to upload.start() as a File. The server sees an ordinary multipart POST — the same route and the same checks Upload describes. The two meet in app code on purpose: the uploader entry pulls in Uppy, the cropper pulls in nothing.

'use client'

import { useEffect, useRef, useState } from 'react'
import {
  Button, Cropper, CropperArea, CropperImage, ResponsiveDialog, ResponsiveDialogClose,
  ResponsiveDialogContent, ResponsiveDialogDescription, ResponsiveDialogFooter,
  ResponsiveDialogHeader, ResponsiveDialogTitle, toast, type CropperAreaData,
} from '@comitor/ui'
import { useFileUpload } from '@comitor/ui/uploader'

const SIZE = 512 // what the server keeps — the canvas resizes for free

export function AvatarPicker({ onSaved }: { onSaved: (image: string) => void }) {
  const [source, setSource] = useState<string | null>(null) // object URL of the chosen file
  const area = useRef<CropperAreaData | null>(null)
  const image = useRef<HTMLImageElement>(null)
  const input = useRef<HTMLInputElement>(null)

  const upload = useFileUpload<{ image: string }>({
    endpoint: '/api/account/avatar',
    maxFileSize: 2 * 1024 * 1024,
    allowedFileTypes: ['image/jpeg', 'image/png'],
    onUploaded: ({ body }) => {
      onSaved(body.image)
      setSource(null)
    },
    onError: ({ message }) => toast(message, { variant: 'destructive' }),
  })

  // An object URL pins the whole file in memory until it is revoked.
  useEffect(() => () => { if (source) URL.revokeObjectURL(source) }, [source])

  async function save() {
    if (!image.current || !area.current) return
    const { x, y, width, height } = area.current
    const canvas = document.createElement('canvas')
    canvas.width = SIZE
    canvas.height = SIZE
    canvas.getContext('2d')?.drawImage(image.current, x, y, width, height, 0, 0, SIZE, SIZE)
    // A type the browser cannot encode silently becomes PNG — trust blob.type, not the argument.
    const blob = await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, 'image/jpeg', 0.9))
    if (blob) upload.start([new File([blob], blob.type === 'image/png' ? 'avatar.png' : 'avatar.jpg', { type: blob.type })])
  }

  return (
    <>
      <input
        ref={input}
        type="file"
        accept="image/png, image/jpeg, image/webp"
        className="sr-only"
        tabIndex={-1}
        onChange={(event) => {
          const file = event.target.files?.[0]
          if (file) {
            area.current = null // the old picture's rectangle means nothing for the new one
            setSource(URL.createObjectURL(file)) // same-origin: the canvas stays untainted
          }
          event.target.value = '' // choosing the same file again must fire change again
        }}
      />
      <Button variant="outline" onClick={() => input.current?.click()}>Change picture</Button>

      <ResponsiveDialog open={source !== null} onOpenChange={(open) => { if (!open) setSource(null) }}>
        <ResponsiveDialogContent>
          <ResponsiveDialogHeader>
            <ResponsiveDialogTitle>Crop your picture</ResponsiveDialogTitle>
            <ResponsiveDialogDescription>Drag to move it. Scroll, pinch, or press + and - to zoom.</ResponsiveDialogDescription>
          </ResponsiveDialogHeader>
          {source ? (
            <Cropper
              aspectRatio={1}
              shape="circle"
              className="min-h-72 rounded-xl"
              // On phones this dialog is a vaul Drawer: without this, dragging the picture
              // downwards also drags the sheet shut.
              data-vaul-no-drag=""
              // Keep the LATEST area — onCropComplete skips the first load.
              onCropAreaChange={(_, pixels) => { area.current = pixels }}
            >
              <CropperImage ref={image} src={source} alt="The picture you chose" />
              <CropperArea />
            </Cropper>
          ) : null}
          <ResponsiveDialogFooter>
            <ResponsiveDialogClose asChild>
              <Button variant="outline">Cancel</Button>
            </ResponsiveDialogClose>
            <Button loading={upload.busy} onClick={() => void save()}>Save</Button>
          </ResponsiveDialogFooter>
        </ResponsiveDialogContent>
      </ResponsiveDialog>
    </>
  )
}

Note the data-vaul-no-drag on the cropper. On a phone, Responsive Dialog renders a vaul drawer, and vaul listens for pointer moves anywhere in the sheet: without the attribute, a downward drag on the picture pans it and pulls the sheet shut.

Language

Four strings, all for assistive technology, in the cropper namespace: label, roleDescription, instructions and zoomStatus(zoom) — a function, because the percentage sits inside the sentence. DEFAULT_CROPPER_LABELS is the English table (since 3.0.0); the Vietnamese one is comitorMessagesVi.cropper. The labels prop beats the nearest ComitorLocaleProvider, which beats English — and aria-label passed straight to the cropper beats all three. Switch the language, then focus the cropper and press +:

Xem trướcMã

EnglishTiếng Việt

aria-label

aria-roledescription

instructions (aria-describedby)

live region, after + or - in the cropper

—

The picture’s alt is yours and moves with the page’s language. How to set the provider once for a whole app: Get started → Set the language.

Props

Cropper. The types CropperAreaData, CropperPoint, CropperSize, CropperMediaSize, CropperShape, CropperObjectFit and CropperLabels are exported alongside.

CropperImage and CropperVideo — everything else goes to the <img> or <video>.

CropperArea.

The hook — for decoration inside the cropper. Anything outside it reads the callbacks instead.

Known limitations

• It produces a rectangle, never pixels. Drawing, encoding and uploading are the app’s job, as above. shape="circle" changes only the frame: the area is the bounding square, so round it in CSS or clip the canvas before encoding.
• Pictures from another origin taint the canvas. drawImage still works, but toBlob throws a SecurityError. Serve them with CORS headers and set crossOrigin="anonymous" on CropperImage, or use an object URL of the chosen file.
• Rotation needs more than one drawImage. With rotation set, the area is measured on the rotated bounding box, so rotate the canvas before drawing. No key rotates — a rotation control is yours to build.
• onCropComplete misses the first load and prop changes. Nor does it close a trackpad pinch in desktop Safari, which arrives as gesture events rather than wheel events. Keep the latest onCropAreaChange for Save, or a picture nobody touched — or zoomed only with your slider — has no area.
• The wheel belongs to the cropper. Over it, scrolling zooms and the page does not move. In a long form, pass preventScrollZoom and give zoom a slider.
• Touch never scrolls the page from the cropper. It is touch-action: none; on a phone, keep some page outside it to scroll by.
• Inside a drawer, the sheet drags too. Put data-vaul-no-drag on the cropper, as in the upload example.

Accessibility

• The cropper element is role="application" with tabIndex=0, named by labels.label (“Image crop area”), described as “image cropper” through aria-roledescription, and linked to the key instructions by aria-describedby. Pass aria-label to say what is being cropped — “Profile picture”, “Company logo”.
• Keyboard: Tab reaches the cropper. ← ↑ → ↓ move the picture by keyboardStep pixels, a fifth of that with Shift; + / = zoom in and - / _ zoom out by 0.1. Holding a key repeats it; releasing it ends the interaction.
• Each keyboard zoom is announced through a polite live region (“Zoom 110%”). Wheel and pinch zoom are visual gestures and are not announced.
• The focus ring is outline-ring, 2px, drawn inside the cropper on ::after so the picture cannot cover it.
• Give CropperImage a real alt: the picture is the content being edited.
• It is not a form control: nothing is posted and no input is rendered. The rectangle leaves through the callbacks, and the app sends it — or the cropped file — itself.
• What the app still owns: names for its own controls (the zoom slider above takes aria-label, which a single-thumb Slider puts on its thumb since 3.0.1), a Cancel, a visible and announced result after the upload (“Profile picture updated”), and a rotation control if rotation matters.
• Contrast is measured against the picture, not the page: the frame is paper over an ink overlay, 4.65:1 at worst; the thirds grid is decoration and is allowed to disappear on a white sky.

Related

• Upload — useFileUpload, ImageUploadField and the server route the cropped file goes to.
• Responsive Dialog — the usual home for a crop step: a dialog on desktop, a sheet on phones.
• HR — employee photos on profiles and directories.
• Social — profile pictures and cover images.
• Commerce — product photos cut to one shape for a catalogue grid.
• Slider and Avatar — the zoom control, and where the result ends up.