React PDF Viewer: Suche, Highlights, echte Annotationen

Du hast einen Vertrag, eine Rechnung oder ein Paper als PDF, und deine App muss es anzeigen. Ein <iframe> gibt die Aufgabe an den eingebauten Viewer des Browsers ab. Den kannst du weder gestalten noch übersetzen, an seine Events kommst du nicht heran, und er sieht in jedem Browser anders aus. Ein React PDF Viewer gibt dir diese Kontrolle zurück: deine Toolbar, deine Suche, deine Events. Die schwierigen Teile kommen erst, wenn die erste Seite steht: eine Datei mit 200 Seiten schnell halten, Text bei 300% scharf halten, die Ansicht am Smartphone bedienbar machen und Leute Passagen markieren lassen, ohne dass die Markierungen verloren gehen, sobald die Datei deine App verlässt. Dieser Guide behandelt genau diese Teile am Beispiel des PDF Viewers von Wingo UI. Wir bauen Wingo UI, sind also nicht neutral; Fakten von außen verlinken auf ihre Quellen.

Was muss ein React PDF Viewer können?

Ein Viewer, in dem Leute arbeiten, braucht sieben Dinge, und mit jeder Library ist nur das Rendern der ersten Seite leicht:

1. Virtualisierte Seiten. Nur die Seiten im sichtbaren Bereich werden gerendert, dadurch öffnet sich eine lange Datei so schnell wie eine kurze.
2. Scharfer Zoom. Bei starkem Zoom wird ein einzelnes Canvas pro Seite riesig, deshalb werden gezoomte Seiten in Kacheln gezeichnet.
3. Suche, die jeden Treffer markiert, mit einem Zähler wie „2 von 5“ und Enter, um durch die Treffer zu springen.
4. Thumbnails, um durch die Datei zu springen, und eine Seitendrehung, die der Download übernimmt.
5. Auswählbarer Text, damit Leute eine Klausel kopieren, statt sie abzutippen.
6. Ein Smartphone-Layout: Wischen scrollt, langes Drücken wählt Text aus, Panels schieben sich über die Seite.
7. Highlights und Notizen, falls Leute das Dokument prüfen, gespeichert an einer Stelle, an der deine App sie lesen kann.

react-pdf, der häufigste Einstieg, überlässt Punkt 7 komplett dir.

Welche React PDF Viewer Libraries sollte ich vergleichen?

Vergleiche react-pdf, react-pdf-highlighter, react-pdf-viewer, EmbedPDF und den PDF Viewer von Wingo UI. Jede dieser Optionen baut auf einer von zwei Engines auf: pdf.js (opens in a new tab) von Mozilla (JavaScript, Apache 2.0) oder PDFium (opens in a new tab) von Google (C++, die Engine in Chromium), kompiliert zu WebAssembly. Die Fakten stammen aus dem GitHub-README und dem npm-Eintrag des jeweiligen Projekts, Stand Oktober 2026.

Wenn du einen React PDF Viewer kostenlos in einer kommerziellen App nutzen willst und die UI selbst baust, ist react-pdf der bewährte Weg. EmbedPDF ist die bessere Wahl, wenn du Annotationen willst, ohne für eine Komponente zu zahlen. Nimm react-pdf-highlighter, wenn Highlights immer nur in deiner Datenbank liegen. Verzichte bei neuen Projekten auf react-pdf-viewer: Das Repository ist archiviert. Der Rest dieses Guides behandelt den Viewer von Wingo UI.

Warum PDFium in React nutzen?

Weil PDFium ein PDF lesen und schreiben kann. Der Viewer lädt das PDFium-Binary (etwa 4 MB, einmal geladen und dann gecacht) in einen Web Worker, damit Parsen und Zeichnen nicht den Main Thread blockieren, und alle Viewer auf der Seite teilen sich diesen einen Worker. Dieselbe Engine, die die Seiten rendert, liest auch die Annotationen, die schon in der Datei stehen, und schreibt beim Export neue hinein. Mit PDFium in React machen Highlights so den Weg in die Datei und wieder zurück. Gerendert wird im Browser, und ein PDF, das jemand auf den Viewer zieht, öffnet sich aus dem Speicher, ohne Upload.

npx wingo-ui@latest add pdf-viewer

Die CLI kopiert components/ui/pdf-viewer.tsx, fügt Button, Popover, Tooltip und Dropdown Menu sowie die gemeinsamen Hooks des Viewers hinzu und installiert die @embedpdf/*-Pakete, pdf-lib (um Drehungen in Downloads zu schreiben) und lucide-react.

import { PdfViewer } from "@/components/ui/pdf-viewer";

export default function ContractPage() {
  return <PdfViewer src="/files/service-agreement.pdf" fileName="service-agreement.pdf" height="80dvh" author="Emma Carter" />;
}

src nimmt eine URL vom selben Origin, eine URL mit CORS-Freigabe oder eine blob:-URL. Ohne src zeigt der Viewer einen Empty State, der nach einer Datei fragt, und onPdfUpload gibt dir die Datei, die jemand ausgewählt oder hineingezogen hat. Kombinier ihn mit dem File Upload, wenn das PDF auch auf deinen Server soll; der Guide zum React File Upload deckt diesen Teil ab.

Scroll durch den Vertrag, gib eine Seitenzahl ein, öffne die Suche und probier ein Wort wie „fee“:

Welche Props braucht der PDF Viewer?

Nötig ist nur src, und als Zweites setzt du height. Der Viewer füllt die Höhe, die du ihm gibst (standardmäßig 640, eine Zahl für px oder jede CSS-Länge wie "100%", um einen Bereich zu füllen). Danach greifst du vor allem zu diesen Props:

• defaultZoom: "automatic" (der Standard) passt die Seite an die Breite an, höchstens bis 100%, damit sie sich auf einem großen Bildschirm nie aufgeblasen und auf dem Smartphone nie abgeschnitten öffnet. "fit-page", "fit-width" oder eine Zahl gehen auch. zoomLevels legt die Stufen im Zoom-Menü fest.
• variant (surface, outline, plain) und radius für den Rahmen.
• showToolbar, showThumbnails, showSearch, showRotateControls, showDownload, showUpload, um die Bedienelemente zu reduzieren.
• toolbarActions für eigene Buttons vor dem ⋯-Menü: Teilen, Unterschreiben, Freigeben.
• onActivePageChange und onDocumentLoadSuccess(numPages), um eine Anzeige wie „Seite 3 von 12“ an anderer Stelle deiner UI synchron zu halten.
• labels für jeden Text, zusammengeführt mit DEFAULT_PDF_VIEWER_LABELS, und locale für die Datumsangaben im Highlights-Panel.

renderPageOverlay zeichnet über jede Seite und dreht sich mit, etwa für Quellenangaben oder Bounding Boxes aus einem Modell zur Dokumentextraktion; ref.scrollToPageArea(page, { top, left, width, height }) in Prozent der Seite scrollt zu einer davon.

React PDF Viewer Highlight: Wie baue ich die Funktion ein?

Die hast du schon: highlighting ist standardmäßig an, und du steuerst das Array highlights. Wähl Text aus, und eine Leiste öffnet sich mit fünf Farben, Unterstreichen, Durchstreichen, „Add note“ und „Copy“. Strg+Shift+H (⇧⌘H auf dem Mac) markiert die Auswahl oder schaltet den Highlighter um, einen Modus, in dem alles, was du auswählst, beim Loslassen sofort markiert wird. Klick auf ein Highlight, um Farbe oder Notiz zu ändern, und Strg+Z / ⌘Z macht Änderungen rückgängig.

Jedes Highlight ist einfaches JSON: { id, page, rects, text, color, type, note, author, createdAt }, mit rects in PDF-Punkten ab der oberen linken Ecke der ungedrehten Seite. Weil es Seitenkoordinaten sind, sitzt ein gespeichertes Highlight bei jedem Zoom und jeder Drehung an der richtigen Stelle. Steuer die Liste wie jedes Eingabefeld:

"use client";

import { useState } from "react";
import { PdfViewer, type PdfViewerHighlight } from "@/components/ui/pdf-viewer";

export function ContractReview({ documentId, initial }: { documentId: string; initial: PdfViewerHighlight[] }) {
  const [highlights, setHighlights] = useState(initial);

  return (
    <PdfViewer
      src={`/api/documents/${documentId}/file`}
      fileName="service-agreement.pdf"
      author="Emma Carter"
      height="80dvh"
      highlights={highlights}
      onHighlightsChange={(next) => {
        setHighlights(next);
        // die ganze liste, nach jedem hinzufügen, bearbeiten, löschen, rückgängig machen, wiederholen und import
        void fetch(`/api/documents/${documentId}/highlights`, {
          method: "PUT",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(next),
        });
      }}
    />
  );
}

Speicherst du eine Zeile pro Highlight, nimm onHighlightAdd, onHighlightChange und onHighlightRemove. Für Annotationen, die aus der Datei importiert werden, feuert nur onHighlightsChange; sie kommen einmal pro Dokument in die Liste, anhand der id zusammengeführt.

Setz highlighting={false} für eine schreibgeschützte Prüfansicht: Highlights, die du übergibst (oder die die Datei mitbringt), werden weiter angezeigt und öffnen sich mit ihren Notizen, aber nichts lässt sich ändern. Das Highlights-Panel listet jedes Highlight mit Seite, Notiz, Autor und Datum, filterbar nach Farbe; showHighlightsPanel={false} blendet es aus, wenn deine App eine eigene Liste zeigt.

Wie kann ich PDF-Annotationen aus React exportieren?

Ruf exportPdf() auf dem Ref auf. Die Methode liefert einen Blob der Datei, in dem jedes Highlight als echte Markup-Annotation steht (/Highlight, /Underline oder /StrikeOut), mit Notiz und Autor, dazu alle Seitendrehungen. Der Export arbeitet auf einer Kopie. Acrobat, Preview und Chrome zeigen die Annotationen an, und wenn du die Datei erneut im Viewer öffnest, kommen sie als bearbeitbare Highlights zurück. Willst du PDF-Annotationen exportieren, ohne dass jemand einen Download-Button drückt, schick den Blob an deinen Server, wie hier:

"use client";

import { useRef } from "react";
import { Button } from "@/components/ui/button";
import { PdfViewer, type PdfViewerHandle } from "@/components/ui/pdf-viewer";

export function SignedCopy({ documentId }: { documentId: string }) {
  const viewer = useRef<PdfViewerHandle>(null);

  const saveAnnotatedCopy = async () => {
    const blob = await viewer.current?.exportPdf();
    if (!blob) return;
    await fetch(`/api/documents/${documentId}/annotated`, {
      method: "PUT",
      headers: { "Content-Type": "application/pdf" },
      body: blob,
    });
  };

  return (
    <PdfViewer
      ref={viewer}
      src={`/api/documents/${documentId}/file`}
      author="Liam Brooks"
      height={600}
      toolbarActions={<Button size="sm" onClick={saveAnnotatedCopy}>Kopie speichern</Button>}
    />
  );
}

Ist importHighlights an (der Standard), werden Markup-Annotationen, die schon in der Datei stehen, zu Highlights und beim Export durch deine Liste ersetzt; ein im Viewer gelöschtes Highlight verschwindet also auch aus der Datei. Leser bekommen denselben Export über das ⋯-Menü.

Wie funktioniert der PDF Viewer am Smartphone?

Das Layout richtet sich nach der Breite des Viewers selbst, ein schmaler Viewer in einem Seitenpanel am Desktop verhält sich also ebenfalls wie auf einem Smartphone. Unter 520px startet die Thumbnail-Sidebar geschlossen und schiebt sich über die Seiten. Unter 600px wandern die Buttons zum Drehen ins ⋯-Menü, unter 440px auch der Highlights-Schalter. Das Highlights-Panel steht ab 900px neben den Seiten, bei schmaleren Viewern schiebt es sich über sie.

Auf Touch-Geräten scrollst du durch Wischen. Langes Drücken wählt das Wort unter deinem Finger aus, und Ziehen erweitert die Auswahl Wort für Wort. Die Farbleiste sitzt fest am unteren Rand des Viewers (oder am oberen, wenn die Auswahl dort unten liegt), und die Details eines Highlights öffnen sich als Bottom Sheet. Buttons in Toolbar und Auswahlleiste wachsen bei Touch-Bedienung (coarse pointer) auf 44px. Der Guide zu Mobile-First-React-Komponenten erklärt diese Regeln.

Ist der PDF Viewer barrierefrei?

Ja, er funktioniert mit Tastatur und Screenreader. Die Toolbar hat role="toolbar" und beschriftete Buttons. Im Seitenfeld springst du mit Enter zur Seite, mit Pfeil hoch und runter seitenweise weiter, und Escape bricht ab. Die Zahl der Suchtreffer wird über eine Live Region angesagt. Die Thumbnails sind eine Listbox mit Mehrfachauswahl: Pfeil hoch und runter bewegen den Fokus, Pos1 und Ende springen an den Anfang und ans Ende, Shift erweitert die Auswahl, die Leertaste wählt an oder ab. Im Highlights-Panel bewegen Pfeil hoch und runter den Fokus, Entf löscht. Strg+F / ⌘F öffnet die Suche nur, solange der Fokus im Viewer liegt, damit die Suche des Browsers für den Rest der Seite weiter funktioniert. Denk daran: Ein PDF ist nur so barrierefrei wie seine Textebene. Eine gescannte Datei ohne OCR hat keinen Text, den man durchsuchen, auswählen oder markieren kann.

Welche Stolperfallen gibt es?

• CORS. Ein PDF auf einer anderen Domain braucht CORS-Header, sonst schlägt der Fetch fehl und der Viewer zeigt seinen Fehlerzustand. Andernfalls leitest du es über eine eigene Route weiter.
• Eine strenge Content Security Policy. WebAssembly braucht 'wasm-unsafe-eval' in script-src. Das Binary kommt standardmäßig von jsDelivr; um es selbst zu hosten, kopier node_modules/@embedpdf/pdfium/dist/pdfium.wasm nach public/ und übergib wasmUrl="/pdfium.wasm".
• Keine Höhe. Der Viewer wächst nicht mit seinen Seiten. Gib ihm height oder ein Elternelement mit fester Höhe und height="100%".
• Word-Dateien. PDFium liest nur PDF. Für .docx nimmst du den DOCX Viewer; der Guide zum React DOCX Viewer erklärt, wann du eine Word-Datei besser in ein PDF umwandelst.

Wie baue ich ihn in mein Projekt ein?

Führ npx wingo-ui@latest add pdf-viewer aus. Der PDF Viewer ist eine Pro-Komponente (Preise), und auf seiner Doku-Seite findest du weitere Beispiele, von einer reinen Prüfansicht mit Button zum Unterschreiben bis zu Quellenangaben auf einer Rechnung. Für Tabellendateien behandelt der Guide zum React Excel Viewer .xlsx-Dateien, und die Kategorie Komponenten-Guides hat weitere Deep Dives zu einzelnen Komponenten.

Häufige Fragen

Welcher kostenlose React PDF Viewer ist der beste?

Als kostenlose Option unter MIT rendert react-pdf von Wojciech Maj Seiten, Thumbnails und eine Gliederung auf Basis von pdf.js; Toolbar, Suche und Highlights baust du selbst. EmbedPDF ist ein Open-Source-Viewer auf einem PDFium-Fork, den du direkt in eine Seite einsetzt. Der PDF Viewer von Wingo UI ist eine Pro-Komponente auf Basis der EmbedPDF-Plugins, mit fertiger Toolbar, einem Highlights-Panel und Highlights als JSON in deinem State.

Wie markiere ich Text in einem PDF mit React?

Du brauchst die Textpositionen auf der Seite, einen Weg, eine Auswahl in Rechtecke in PDF-Punkten umzurechnen, und eine Ebene, die sie bei jedem Zoom und jeder Drehung zeichnet. Der PDF Viewer übernimmt das: Text auswählen, in der Leiste neben der Auswahl eine Farbe wählen, und das Highlight landet im highlights-Array, das du mit onHighlightsChange übergibst.

Kann ich Highlights direkt in der PDF-Datei speichern?

Ja, wenn sie als Markup-Annotationen geschrieben werden. ref.exportPdf() des PDF Viewers liefert einen Blob, in dem jedes Highlight als /Highlight-, /Underline- oder /StrikeOut-Annotation mit Notiz und Autor steht. Andere PDF-Reader zeigen sie an, und der Viewer lädt sie wieder, wenn die Datei erneut geöffnet wird.

Was ist der Unterschied zwischen pdf.js und PDFium?

pdf.js ist der in JavaScript geschriebene PDF-Renderer von Mozilla unter Apache 2.0. PDFium ist die C++-PDF-Engine, die in Chromium steckt; zu WebAssembly kompiliert läuft sie im Browser in einem Web Worker. Beide rendern im Browser, die Datei muss also nicht an einen Server.

Ist der PDF Viewer von Wingo UI kostenlos?

Nein. Der PDF Viewer ist eine Pro-Komponente. Button, Tooltip, Popover und Dropdown Menu, aus denen er gebaut ist, sind kostenlos.