React Image Cropper: Zuschnitt vor dem Upload, Zoom, Drehung

Du lässt Leute ein Profilfoto oder ein Bild für ein Inserat hochladen, und was ankommt, sind JPEGs mit 4.000 Pixeln, seitlich gedrehte Gesichter und Köpfe, die object-fit: cover abschneidet. Ein React Image Cropper löst das, bevor die Datei den Browser verlässt: Die Person wählt den Ausschnitt, du exportierst ein kleines Bild in genau der Größe, die du brauchst, und der Server speichert das, was die Seite auch zeigt. Dieser Guide zeigt, was ein Cropper können muss, wie sich die üblichen Libraries unterscheiden, wie du mit dem Image Cropper von Wingo UI ein Bild vor dem Upload zuschneidest und wie der runde Avatar-Ablauf darauf aufbaut.

Was muss ein React Image Cropper können?

Ein Cropper, der im Produktivbetrieb besteht, beherrscht sieben Dinge:

1. Verschieben und Zoomen per Maus-Drag, Mausrad, Ziehen mit einem Finger und Pinch mit zwei Fingern, wobei das Foto den Rahmen immer ausfüllt.
2. Seitenverhältnisse: ein festes für Cover und Avatare, Presets für Galerien und ein freier Zuschnitt mit Ecken, an denen du die Größe änderst.
3. Drehung: 90-Grad-Drehungen für seitlich liegende Fotos und ein feiner Slider, um einen Horizont gerade zu richten.
4. Ein Export in fester Größe: eine exakte Breite oder eine Obergrenze für die längste Seite, in WebP, JPEG oder PNG, als Blob, den du in FormData steckst.
5. Ein runder Rahmen für Avatare und Logos, mit transparenten Ecken im Export.
6. Tastaturbedienung: Pfeiltasten zum Verschieben, Tasten zum Zoomen und Drehen und Slider, deren Wert der Screenreader vorliest.
7. Ein Smartphone-Layout, in dem die Toolbar auf dem Bildschirm bleibt und jedes Bedienelement eine Touch-Fläche von 44px hat.

An Punkt 4 scheitern selbst gebaute Cropper meistens. Wer ein großes Foto mit einem einzigen drawImage-Aufruf direkt auf 512px verkleinert, kann gezackte Kanten bekommen, und ein Canvas über dem Größenlimit des Browsers kann fehlschlagen oder leer bleiben.

Welche React Image Crop Library soll ich nehmen?

Diese Namen fallen, wenn du nach einer React Image Crop Library suchst (oder auf Deutsch nach „React Bild zuschneiden“). Die Fakten stammen aus dem README des jeweiligen Projekts auf GitHub, Stand Oktober 2026.

react-image-crop ist die bessere Wahl, wenn Nutzer einen Rahmen über ein Dokument oder einen Screenshot ziehen sollen und wenn die Bundle-Größe am meisten zählt. react-easy-crop passt zu Fotos, denn das Bild unter einem festen Rahmen zu verschieben fühlt sich auf dem Smartphone natürlicher an. Die Komponente von Wingo UI ist react-easy-crop mit fertiger UI und fertigem Export, als Quellcode, den du ändern kannst.

Wie kann ich in React ein Bild vor dem Upload zuschneiden?

Setz den Cropper zwischen Dateiauswahl und Upload. Der Image Cropper nimmt eine File als src (er erzeugt die Object-URL und gibt sie wieder frei), und setApi gibt dir ein Handle mit toBlob. Wer in React ein Bild vor dem Upload zuschneiden will, braucht drei Teile: ein Datei-Input, den Cropper und den Upload-Aufruf.

npx wingo-ui@latest add image-cropper

"use client";

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

export function CoverPhotoField() {
  const [file, setFile] = useState<File | null>(null);
  const [api, setApi] = useState<ImageCropperApi | null>(null);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState("");
  const inputRef = useRef<HTMLInputElement>(null);

  const onPick = (event: ChangeEvent<HTMLInputElement>) => {
    const picked = event.target.files?.[0];
    if (picked) setFile(picked);
    // dieselbe datei lässt sich erneut auswählen
    event.target.value = "";
  };

  const save = async () => {
    if (!api) return;
    setSaving(true);
    setError("");
    try {
      const blob = await api.toBlob({ type: "image/webp", quality: 0.85, maxSize: 1600 });
      const body = new FormData();
      body.append("cover", blob, "cover.webp");
      const response = await fetch("/api/listings/cover", { method: "POST", body });
      if (!response.ok) throw new Error("Der Upload ist fehlgeschlagen");
    } catch (failure) {
      setError(failure instanceof Error ? failure.message : "Der Upload ist fehlgeschlagen");
    } finally {
      setSaving(false);
    }
  };

  return (
    <div className="flex max-w-xl flex-col gap-4">
      <input ref={inputRef} type="file" accept="image/jpeg,image/png,image/webp" className="sr-only" tabIndex={-1} onChange={onPick} />
      {file && <ImageCropper src={file} defaultAspect={16 / 9} setApi={setApi} />}
      <div className="flex gap-2">
        <Button variant="soft" onClick={() => inputRef.current?.click()}>
          Foto auswählen
        </Button>
        <Button loading={saving} disabled={!file} onClick={save}>
          Cover speichern
        </Button>
      </div>
      {error && <p role="alert" className="text-sm text-destructive-soft-foreground">{error}</p>}
    </div>
  );
}

defaultAspect legt das Startverhältnis fest und lässt die Presets (Free, 1:1, 4:3, 3:4, 16:9, 9:16) verfügbar; mit aspectPresets={false} sperrst du das Verhältnis. onValueChange feuert erst am Ende einer Interaktion, nie pro Frame, und liefert einen CropValue: den Bereich in Pixeln des Originalbilds, Zoom, Drehung, Seitenverhältnis und Spiegelung.

Wie exportiere ich aus dem Zuschnitt ein WebP in fester Größe?

Gib toBlob Export-Optionen mit oder setz sie einmal über die Prop export. maxSize begrenzt die längste Seite und vergrößert nie, width und height setzen eine exakte Größe, type wählt image/webp, image/jpeg oder image/png, und quality (0 bis 1) gilt für WebP und JPEG. Ohne Optionen ist der Export ein JPEG mit 90% Qualität, begrenzt auf 2048px.

Drei Details des Exports solltest du kennen, bevor du deinen eigenen schreibst:

• Stufenweises Verkleinern. Der Ausschnitt wird zuerst in einem Vielfachen der Zielgröße gezeichnet, das eine Zweierpotenz ist (nie über der Auflösung des Originals), dann Schritt für Schritt halbiert, solange die nächste Hälfte noch mindestens so groß wie das Ziel ist, und erst dann in der Endgröße gezeichnet. Ein großes Smartphone-Foto, das du mit 512px exportierst, bleibt so scharf, statt Treppenstufen zu bekommen.
• Eine Obergrenze für das Canvas. Das Arbeits-Canvas wird nie größer als 16.777.216 Pixel (4096 mal 4096). Ein riesiges Foto wird deshalb verkleinert, und der Export bleibt nicht leer.
• Keine Metadaten. Die Datei wird aus einem Canvas neu kodiert und enthält deshalb keine EXIF-Daten, womit auch der GPS-Standort wegfällt, den ein Smartphone in Fotos schreibt. Aktuelle Browser wenden die EXIF-Ausrichtung an, wenn sie das Foto zeichnen (image-orientation (opens in a new tab) steht standardmäßig auf from-image). Vorschau und Export stimmen also überein.

JPEG kennt keine Transparenz, also füllt der Export den Hintergrund weiß, solange du kein background übergibst. Kann ein Browser den gewünschten Typ nicht kodieren, fällt canvas toBlob (opens in a new tab) auf PNG zurück. Lies also blob.type, bevor du die Datei benennst.

React Image Crop Circle: Wie schneide ich ein Bild rund zu?

Setz cropShape="round". Der Rahmen wird zum Kreis, das Seitenverhältnis wird auf 1 festgelegt, die Presets verschwinden, und der Export maskiert den Kreis standardmäßig. Wähl PNG oder WebP, damit die Ecken transparent bleiben:

"use client";

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

export function LogoCrop({ file, onDone }: { file: File; onDone: (blob: Blob) => void }) {
  const [crop, setCrop] = useState<CropValue | null>(null);

  const save = async () => {
    if (!crop) return;
    onDone(await cropImage(file, crop, { type: "image/png", width: 512, height: 512, round: true }));
  };

  return (
    <div className="flex flex-col gap-4">
      <ImageCropper src={file} cropShape="round" rotatable={false} onValueChange={setCrop} />
      <Button onClick={save} disabled={!crop}>
        Logo speichern
      </Button>
    </div>
  );
}

cropImage führt denselben Export ohne die Komponente aus, aus der Originaldatei und einem gespeicherten CropValue. Dieses Muster nimmst du, wenn du später neu zuschneiden willst: Bewahr den Original-Upload und den Crop-Wert auf, übergib den Wert wieder als defaultValue, wenn die Person das Bild erneut bearbeitet, und erzeug jede Größe, die du brauchst, neu.

Wie baue ich einen React Avatar Upload mit Zuschnitt?

Nimm Avatar Upload, das den Cropper in den kompletten Ablauf für Profilfotos einbaut. Tippst du auf den Avatar, öffnet sich ein Menü („Choose a photo“, „Take photo“ und „Remove photo“, wenn du onRemove übergibst), zugeschnitten wird in einem runden Rahmen in einem Dialog, und „Save“ exportiert ein quadratisches WebP mit 512px. Das neue Bild erscheint sofort, während sich ein Ring um den Avatar mit dem Upload-Fortschritt füllt. Scheitert der Upload, kommt das alte Bild zurück, und die Komponente bietet „Try again“ an.

npx wingo-ui@latest add avatar-upload

"use client";

import { useState } from "react";
import { AvatarUpload } from "@/components/ui/avatar-upload";

export function ProfilePhoto({ initial }: { initial: string | null }) {
  const [avatar, setAvatar] = useState<string | null>(initial);

  return (
    <AvatarUpload
      name="Emma Carter"
      value={avatar}
      onValueChange={setAvatar}
      outputSize={512}
      outputType="image/webp"
      onUpload={(blob, { signal, onProgress }) =>
        new Promise<string>((resolve, reject) => {
          const request = new XMLHttpRequest();
          // fetch meldet keinen upload-fortschritt, XMLHttpRequest schon
          request.upload.onprogress = (event) => {
            if (event.lengthComputable) onProgress(event.loaded / event.total);
          };
          request.onload = () =>
            request.status < 300
              ? resolve((JSON.parse(request.responseText) as { url: string }).url)
              : reject(new Error("Der Upload ist fehlgeschlagen"));
          request.onerror = () => reject(new Error("Die Verbindung ist abgebrochen"));
          request.onabort = () => reject(new DOMException("Aborted", "AbortError"));
          signal.addEventListener("abort", () => request.abort());
          const body = new FormData();
          body.append("avatar", blob, "avatar.webp");
          request.open("POST", "/api/profile/avatar");
          request.send(body);
        })
      }
      onRemove={() => fetch("/api/profile/avatar", { method: "DELETE" })}
    />
  );
}

Löst du das Promise mit der gespeicherten URL auf, wird sie zum neuen Wert. Ohne Aufrufe von onProgress dreht sich der Ring, statt sich zu füllen. Das signal meldet einen Abbruch, wenn die Komponente unmountet oder ein neuerer Upload startet. variant="row" ergänzt neben dem Avatar die Buttons „Change photo“ und „Remove“ für eine Einstellungsliste, und variant="dropzone" ist eine gestrichelte Kachel für Firmenlogos. crop={false} überspringt den Dialog und lädt das größte zentrierte Quadrat hoch. Über cropperProps stellst du den Zuschneide-Schritt ein, zum Beispiel mit { flippable: true }.

Wie funktioniert das Zuschneiden auf dem Smartphone und mit der Tastatur?

Auf dem Smartphone verschiebt ein Finger das Foto und ein Pinch zoomt. Die Arbeitsfläche ist auf 60% der Bildschirmhöhe begrenzt, damit die Toolbar sichtbar bleibt, die Toolbar stapelt sich, und die Presets für Seitenverhältnisse werden zu einer scrollbaren Chip-Leiste mit 44px großen Touch-Zielen. In Avatar Upload werden Quellen-Menü, Zuschneide-Schritt und Kamera unter 768px zu Bottom Sheets (responsive, standardmäßig an), nach derselben Regel wie im Guide zum responsiven Dialog auf dem Smartphone. „Take photo“ öffnet auf Smartphones die Frontkamera über capture="user" und am Desktop einen Dialog mit Live-Kamera.

Mit der Tastatur springst du per Tab zum Zuschneide-Rahmen: Pfeiltasten verschieben das Foto um 10px (Shift plus Pfeiltaste um 2px), + und - zoomen, r dreht um 90 Grad nach links, f spiegelt, wenn flippable an ist, und 0 setzt zurück. Screenreader lesen die Werte der Slider für Zoom und Drehung als 150% oder −12 Grad vor, und Wechsel des Seitenverhältnisses, Drehungen und Zurücksetzen werden angesagt. Alle Texte, auch die Ansagen, stecken in labels; was du dort übergibst, wird über DEFAULT_IMAGE_CROPPER_LABELS gelegt.

Welche typischen Fehler gibt es bei einem Image Cropper?

• Fremde Bilder ohne CORS. Die Vorschau funktioniert, aber toBlob schlägt mit labels.corsError fehl, weil das Canvas „tainted“ ist. Schneid die File aus dem Input zu oder liefer das Bild mit CORS-Headern aus.
• HEIC-Fotos vom iPhone. Avatar Upload akzeptiert standardmäßig JPEG, PNG und WebP. Safari wandelt HEIC beim Auswählen in JPEG um, wenn JPEG in accept steht; in anderen Browsern fällt eine HEIC-Datei durch die Typprüfung, und die Person sieht labels.wrongType.
• Das Original hochladen. Schickst du die ausgewählte Datei und schneidest erst bei der Anzeige per CSS zu, lädt jeder Besucher das volle Foto herunter. Schick den Export.
• Dem Client vertrauen. Der Export im Browser ist eine Komfortfunktion. Prüf Typ, Größe und Abmessungen auf dem Server noch einmal.
• Auf jeden Frame reagieren. onCropChange feuert bei jedem Frame, solange sich der Ausschnitt bewegt. Speicher bei onValueChange, das einmal pro Interaktion feuert.

Für die Dateiauswahl selbst (Drag and Drop, Einfügen, Prüfung von Typ und Größe, eine Upload-Warteschlange) kombiniert der Guide zum React File Upload den File Upload mit diesem Cropper, und das Tutorial zur React-Einstellungsseite zeigt, wo eine Zeile für das Profilfoto auf einer kompletten Einstellungsseite sitzt.

Wie baue ich es in mein Projekt ein?

Führ npx wingo-ui@latest add image-cropper oder npx wingo-ui@latest add avatar-upload aus. Die CLI kopiert den Quellcode nach components/ui, ergänzt die Komponenten und Helfer, die er importiert, und installiert die nötigen npm-Pakete (react-easy-crop, motion und lucide-react für den Cropper). Beide sind Pro-Komponenten (Preise). Weitere Deep Dives zu einzelnen Komponenten findest du in der Kategorie Komponenten-Guides, und der Guide zu React-Formularkomponenten behandelt die Regeln für Label, Fehler und Touch, die jedes Feld in einem Profilformular teilt.

Häufige Fragen

Welche React Image Crop Library ist die beste?

react-easy-crop ist die übliche Wahl, wenn du Verschieben, Pinch-Zoom und Drehung brauchst, react-image-crop, wenn du einen kleinen Zuschneide-Rahmen ohne Abhängigkeiten willst, dessen Größe man an den Kanten ändert. Beide liefern Crop-Koordinaten und überlassen das fertige Bild dir oder einem Helfer; eine Quellcode-Komponente wie der Image Cropper von Wingo UI ergänzt react-easy-crop um Toolbar und Export.

Wie schneide ich ein Bild in React rund zu?

Zeig einen runden Rahmen an (cropShape="round" in react-easy-crop und im Image Cropper von Wingo UI, circularCrop in react-image-crop) und maskier den Export mit einem runden Clip auf dem Canvas. Exportier PNG oder WebP, damit die Ecken transparent bleiben, denn JPEG hat keinen Alphakanal.

Schneide ich Bilder besser im Client oder auf dem Server zu?

Schneid im Client zu, damit die Person das Ergebnis sieht und der Upload klein bleibt, und prüf Typ, Größe und Abmessungen auf dem Server noch einmal. Wenn du die Originaldatei und die Crop-Koordinaten aufbewahrst, kannst du später neu zuschneiden, ohne die Person erneut zu fragen.

Warum scheitert der Export eines zugeschnittenen Bildes von einer fremden URL?

Ein Bild von einer anderen Origin ohne CORS-Header macht das Canvas „tainted“, und toBlob wirft dann einen SecurityError. Liefer das Bild mit Access-Control-Allow-Origin aus, leite es über deine eigene Domain oder schneid statt einer URL die Datei aus dem Input zu.

Ist der Image Cropper von Wingo UI kostenlos?

Nein. Image Cropper und Avatar Upload sind Pro-Komponenten. Die Avatar-Komponente, in der Avatar Upload das Bild anzeigt, ist kostenlos.