React Excel Viewer: .xlsx mit echten Styles anzeigen

Jemand lädt einen Quartalsbericht hoch, oder deine App speichert Rechnungen als Tabellen, und die Leute sollen die Datei direkt in deinem Produkt lesen, statt sie herunterzuladen und Excel zu öffnen. Ein React Excel Viewer für diesen Job muss mehr können, als Werte in eine Tabelle zu schreiben: Schriften, Füllungen, Rahmen, verbundene Zellen, Zahlenformate und fixierte Kopfzeilen machen einen Bericht erst lesbar. Unten liest du, was du an jedem Viewer prüfen solltest, warum die Umwandlung in HTML die Formatierung verliert und wie Datumswerte und fixierte Bereiche in der Datei wirklich funktionieren. Am Ende steht eine Ansicht, die eine Arbeitsmappe erst zeigt und dann importiert. Der Code nutzt den Excel Viewer von Wingo UI, der Bibliothek, die wir bauen. Wir sind also nicht neutral; Fakten von außen sind mit ihren Quellen verlinkt.

Was sollte ein React Excel Viewer zeigen?

Er sollte die Arbeitsmappe so zeigen, wie ihr Autor sie in Excel gesehen hat, und dabei flüssig scrollen. Ein Tabellenblatt ist genauso Layout wie Datensatz: Fällt das Layout weg, bleibt eine Wand aus Zahlen, die so niemand gestaltet hat. Diese Liste war unser Maßstab beim Bauen, und sie ist ein fairer Test für jeden React XLSX Viewer, den du dir ansiehst:

• Zell-Styles. Schriften, Füllungen, Rahmen, Ausrichtung, Zeilenumbruch, verbundene Zellen, Spaltenbreiten und Zeilenhöhen, ausgeblendete Zeilen und Spalten, Designfarben.
• Zahlenformate. Währung, Prozent, Datum und eigene Formatcodes, formatiert passend zum Locale des Lesers.
• Fixierte Bereiche. Die Kopfzeilen und wichtigen Spalten, die der Autor fixiert hat, bleiben stehen, während der Rest scrollt.
• Blattregister. Jedes sichtbare Blatt als Register, ausgeblendete Blätter fehlen.
• Formeln. Der gespeicherte Wert in der Zelle und die Formel in einer Bearbeitungsleiste.
• Bedingte Formate, Tabellen, Bilder und Diagramme. Farbskalen, Datenbalken, Tabellenformatvorlagen von Excel, ein eingebettetes Logo.
• Tempo. Flüssiges Scrollen in einem Blatt mit Tausenden Zeilen, auch auf dem Smartphone.

Warum geht die Formatierung verloren, wenn du ein Blatt in HTML umwandelst?

Weil die Bibliothek, zu der die meisten Tutorials greifen, zuerst für Daten gebaut ist. Die übliche Antwort heißt SheetJS: Datei lesen, sheet_to_html aufrufen, das Ergebnis einfügen. Die offizielle React-Demo (opens in a new tab) macht genau das mit dangerouslySetInnerHTML. Du bekommst die Werte und ihren formatierten Text. Das Aussehen bekommst du nicht: Laut der Seite zu den Parse-Optionen (opens in a new tab) konzentrieren sich die Parser der Community Edition standardmäßig darauf, Daten auszulesen. Das Flag cellStyles liest einige Style-Metadaten wie Eigenschaften von Zeilen und Spalten, und die Doku führt Zell- und Textformatierung sowie bedingte Formatierung als Funktionen von SheetJS Pro. Die Seite zu den HTML-Hilfsfunktionen (opens in a new tab) sagt dasselbe über CSS-Styles in der erzeugten Tabelle (alles Stand Oktober 2026).

Das ist das richtige Werkzeug, wenn du die Daten brauchst oder viele Formate lesen musst (.xls, .ods, Numbers). Für eine Excel-Viewer-Komponente, in der Kunden Berichte lesen, passt es schlecht: Füllungen, Rahmen, Zahlenformate und fixierte Bereiche müsstest du von Hand nachbauen. Am anderen Ende stehen kommerzielle Tabellen-Controls wie SpreadJS (opens in a new tab) und das Infragistics React Spreadsheet (opens in a new tab). Damit können Leute Zellen bearbeiten, und beide bringen eine eigene Berechnungs-Engine mit; SpreadJS nennt mehr als 500 eingebaute Funktionen (laut den Produktseiten, Stand Oktober 2026). Wenn Leute die Arbeitsmappe ändern müssen, nimm eines davon. Ein Viewer ist zum Lesen da.

Wie kannst du eine Excel-Datei in React anzeigen?

Mit einer Komponente, die das Format lesen kann, reicht eine Zeile JSX. Installier den Viewer:

npx wingo-ui@latest add excel-viewer

import { ExcelViewer } from "@/components/ui/excel-viewer";

export default function ReportPage() {
  return <ExcelViewer src="/reports/q3-sales-report.xlsx" fileName="Umsatzbericht Q3 2026.xlsx" height="80dvh" />;
}

Die Komponentendatei beginnt mit "use client", deshalb kann eine Seite als Server Component sie mit einfachen Props wie diesen rendern. src kann ein Pfad vom selben Origin sein, eine URL mit CORS (ein presigned S3-Link braucht eine CORS-Regel auf dem Bucket) oder eine blob:-URL. Lässt du src leer, zeigt der Viewer eine Startansicht zum Öffnen einer Arbeitsmappe, die eine ausgewählte oder hineingezogene .xlsx oder .csv annimmt.

Intern lädt er die Bytes, entpackt sie mit fflate (etwa 10 KB, geladen mit der ersten Arbeitsmappe statt mit der Seite), liest das XML für Arbeitsmappe, Styles, Design, Tabellen und Zeichnungen mit dem DOMParser des Browsers und wertet die Zelldaten selbst mit einem Zeilenmuster aus. Nichts geht an einen Konvertierungsdienst.

Wie werden Excel-Zahlenformate und Datumswerte dargestellt?

Über den Formatcode, der mit jeder Zelle gespeichert ist, nicht über den Rohwert. Excel speichert eine Zahl und einen Formatcode, und die Zelle zeigt das Ergebnis. Die Spalte „vs Q2“ im Beispielbericht nutzt +0.0%;[Red]-0.0%;0.0%: drei Abschnitte für positiv, negativ und null, negative Werte in Rot. Der Viewer zerlegt diese Abschnitte, die Farbcodes und die eingebauten Formate und formatiert die Zahl dann mit Intl.NumberFormat passend zum Prop locale. Fehlt er, gilt das Locale des UIProvider, danach das des Browsers.

Datumswerte brauchen Sorgfalt, weil Excel sie als fortlaufende Tageszahlen speichert: 45930 ist nur deshalb ein Datum, weil sein Formatcode das sagt. Darum geben naive Parser in einer Datumsspalte fünfstellige Zahlen aus. Der Viewer rechnet in UTC um, damit eine Zeitzone ein Datum nie um einen Tag verschiebt, kommt mit Arbeitsmappen im 1904-Datumssystem zurecht und berücksichtigt den falschen 29. Februar 1900, den Microsoft laut eigener Doku für die Kompatibilität mit Lotus 1-2-3 beibehalten hat (opens in a new tab). Monats- und Tagesnamen kommen ebenfalls aus dem Locale.

Wie funktionieren fixierte Bereiche und Blattregister?

Fixierte Bereiche stehen in der Datei. Die Ansicht jedes Blatts speichert einen Fensterausschnitt mit xSplit und ySplit, und der Viewer hält so viele Spalten und Zeilen fest, zusammen mit den Spalten- und Zeilenköpfen A B C und 1 2 3. Im Beispiel fixiert das Blatt Summary seine ersten fünf Zeilen, und Transactions fixiert Zeile 1 plus die Spalten A und B. Datum und Bestellnummer bleiben also sichtbar, während du durch 2.000 Bestellungen scrollst.

Die Blattregister sitzen unten und scrollen seitwärts. Das Beispiel hat ein ausgeblendetes Blatt „Lists“: Es bekommt kein Register, und das Blattmenü listet alle Blätter. Der Viewer öffnet das Blatt, das beim Speichern der Arbeitsmappe aktiv war, außer du übergibst defaultSheet oder steuerst es mit sheet und onSheetChange. Über die Ref bekommst du zusätzlich goTo, das eine Adresse, einen Bereich auf einem beliebigen Blatt oder einen definierten Namen annimmt. Die Beispielmappe definiert Q3_totals für die Tabelle in Summary:

"use client";

import { useRef, useState } from "react";
import { Button } from "@/components/ui/button";
import { ExcelViewer, type ExcelViewerHandle } from "@/components/ui/excel-viewer";

export function ReportWithJumps() {
  const viewer = useRef<ExcelViewerHandle>(null);
  const [sheet, setSheet] = useState("Summary");

  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-2">
        <Button size="sm" variant="soft" onClick={() => viewer.current?.goTo("Q3_totals", { behavior: "smooth" })}>
          Summen Q3
        </Button>
        <Button size="sm" variant="soft" onClick={() => viewer.current?.goTo("Team!G2:G11", { behavior: "smooth" })}>
          Zielerreichung im Team
        </Button>
        <span className="ms-auto text-sm text-muted-foreground">Blatt: {sheet}</span>
      </div>
      <ExcelViewer ref={viewer} src="/reports/q3-sales-report.xlsx" sheet={sheet} onSheetChange={setSheet} height={560} />
    </div>
  );
}

goTo gibt false zurück, wenn der Bezug in der geöffneten Datei nicht existiert. Willst du einen Button ausblenden, bevor jemand darauf klickt, prüf die sheets und definedNames, die onWorkbookLoadSuccess meldet.

Wie zeigst du eine große Excel-Datei in React an, ohne dass die Seite einfriert?

Teil das Parsen in kurze Aufgaben auf und zeichne nur, was sichtbar ist. Zwei Schritte können eine Seite einfrieren: das Parsen und das Zeichnen. Beim Parsen entpackt fflate die großen Teile der ZIP-Datei in einem Worker. Eine Content Security Policy, die blob:-Worker blockiert, verhindert den Start dieses Workers. Der Viewer fängt diesen Fehler ab und entpackt dann im Main Thread, statt einen Fehler zu zeigen. Das XML muss trotzdem im Main Thread gelesen werden, weil es DOMParser in Workern nicht gibt. Deshalb überspringt der Viewer DOMParser für die Zelldaten, die den Großteil eines großen Blatts ausmachen, und durchsucht Zeilen und Shared Strings in Abschnitten von etwa 12 ms. Zwischen den Abschnitten kommt der Browser zum Zug, also laufen Eingaben und Rendering weiter. Dateien über maxFileSize (standardmäßig 50 MB) werden gar nicht geparst; der Viewer zeigt dann einen Zustand „Datei zu groß“ mit einem Download-Link.

Beim Zeichnen ist das Grid in beide Richtungen mit @tanstack/react-virtual virtualisiert: Nur die sichtbaren Zeilen und Spalten, plus ein paar auf jeder Seite, existieren im DOM. Fixierte Zeilen und Spalten liegen in eigenen Sticky-Ebenen über dem scrollenden Bereich. Sortieren über ein Spaltenmenü ändert nur die Ansicht, und der Download-Button speichert immer die Originaldatei.

Zwei Grenzen solltest du kennen, bevor du live gehst. Formeln werden nicht neu berechnet; die Zellen zeigen die Werte, die Excel gespeichert hat. Und alte binäre .xls-Dateien lehnt der Viewer mit einem Hinweis ab, sie als .xlsx zu speichern.

Wie zeigst du eine große CSV-Datei in React an?

Nimm einen Viewer, der für CSV gebaut ist, denn die Probleme sind andere. Der Excel Viewer öffnet eine .csv als einzelnes Blatt mit fixierter erster Zeile als Kopfzeile, und das reicht für kleine Exporte. Bei großen Dateien kämpft ein React CSV Viewer mit anderem: Es gibt keine Style-Informationen, das Trennzeichen kann ein Semikolon sein, die Kodierung Windows-1252, und die Datei kann Hunderttausende Zeilen haben.

Der CSV Viewer deckt diesen Fall ab. Er liest die Datei in Abschnitten, sodass die ersten Zeilen erscheinen, während der Rest lädt. Er erkennt Trennzeichen, Kodierung und Kopfzeile, erkennt Spalten mit Zahlen, Datumswerten und Booleans und bringt Filter und fixierte Spalten mit. Die Standardwerte sind ein Limit von 100 MB pro Datei und 1.000.000 Zeilen.

import { CsvViewer } from "@/components/ui/csv-viewer";

export function OrdersPreview() {
  return <CsvViewer src="/exports/orders.csv" height="80dvh" defaultFrozenColumns={1} />;
}

Wie liest du Excel-Daten in React für einen Import?

Mit einem Parser, der Zeilen zurückgibt, nicht mit einem Viewer. Ein Viewer ist für Menschen. Wenn dein Code die Daten braucht, für einen Import oder eine Prüfung, nimm die Spreadsheet-Helfer: readSpreadsheet macht aus einer ausgewählten CSV- oder .xlsx-Datei Blätter mit Kopfzeilen und Zeilen, und matchColumns ordnet diese Kopfzeilen deinen Feldern zu. Den kompletten Ablauf aus Hochladen, Zuordnen und Korrigieren liefert der Block CSV Import. Für das Upload-Feld selbst erklärt der Guide zum React File Upload Drag and Drop, Einfügen und Validierung.

Ist der Viewer barrierefrei und auf dem Smartphone nutzbar?

Ja: Tastatur, grundlegende Screenreader-Unterstützung und Touch funktionieren, mit einer Grenze, die du einplanen solltest. Die Tastatur funktioniert wie in Excel: Pfeiltasten, Tab, Enter, Pos1 und Ende, Bild auf und Bild ab, Strg oder Cmd plus Pfeiltaste springt an den Rand der Daten, Shift erweitert die Auswahl, Strg oder Cmd plus C kopiert als tabulatorgetrennten Text. Der scrollende Bereich ist eine fokussierbare Region mit dem Dateinamen als Label, und eine Live-Region im Modus „polite“ sagt Adresse und angezeigten Text der aktiven Zelle an, während sich die Auswahl bewegt. Die Blattregister sind eine echte Tablist.

Die Grenze: Zellen außerhalb des Bildschirms stehen nicht im DOM. Wer einen Screenreader nutzt, bewegt sich also Zelle für Zelle und kann nicht das ganze Blatt als Tabelle durchgehen. Wenn die Daten auf diesem Weg komplett erreichbar sein müssen, biete zusätzlich den Download an oder zeig die Zeilen in einer Data Table.

Auf dem Smartphone bleibt das Grid ein Grid. Bei einer Tabellenkalkulation trägt das Layout Bedeutung, deshalb machen wir hier keine Karten aus den Zeilen, wie wir es für App-Daten im Guide zu responsiven Tabellen tun. Tippst du auf eine Zelle, wird sie ausgewählt und erscheint in der Bearbeitungsleiste, mit zwei Fingern zoomst du, und wenn der Viewer selbst schmaler als 720px ist, wandern die Schalter der Toolbar ins ⋯-Menü, das sich auf Smartphones als Bottom Sheet öffnet.

Ein komplettes Beispiel: eine Arbeitsmappe vor dem Import ansehen

Mit diesem Screen kann jemand eine Arbeitsmappe öffnen oder hineinziehen, sie mit ihrer Formatierung lesen und dann das Blatt importieren, das gerade offen ist. Die Datei verlässt den Browser erst, wenn dein Import-Code sie sendet.

"use client";

import { useRef, useState } from "react";
import { Button } from "@/components/ui/button";
import { ExcelViewer, type ExcelViewerHandle } from "@/components/ui/excel-viewer";
import { readSpreadsheet, SpreadsheetError, type SpreadsheetErrorCode } from "@/lib/spreadsheet";

const IMPORT_ERRORS: Record<SpreadsheetErrorCode, string> = {
  unsupported: "Speichere die Datei als .xlsx oder .csv und versuch es noch einmal.",
  "too-large": "Diese Datei liegt über dem Import-Limit von 20 MB.",
  empty: "Diese Datei hat keine Zeilen zum Importieren.",
  parse: "Diese Datei lässt sich nicht importieren.",
};

export function WorkbookImport() {
  const viewer = useRef<ExcelViewerHandle>(null);
  const [file, setFile] = useState<File | null>(null);
  const [status, setStatus] = useState("Öffne eine .xlsx oder .csv oder zieh sie auf den Viewer.");

  async function importRows() {
    if (!file) return;
    try {
      const { sheets } = await readSpreadsheet(file);
      const active = viewer.current?.getSelection()?.sheet;
      const target = sheets.find((sheet) => sheet.name === active) ?? sheets[0];
      const skipped = target.truncated ? `, ${target.truncated.toLocaleString("de-DE")} über dem Zeilenlimit` : "";
      setStatus(`Bereit zum Import: ${target.rows.length.toLocaleString("de-DE")} Zeilen aus ${target.name}${skipped}.`);
    } catch (error) {
      if (!(error instanceof SpreadsheetError)) throw error;
      setStatus(IMPORT_ERRORS[error.code]);
    }
  }

  return (
    <div className="flex flex-col gap-3">
      <ExcelViewer
        ref={viewer}
        height="70dvh"
        onWorkbookUpload={setFile}
        onWorkbookLoadSuccess={(workbook) => setStatus(`${workbook.fileName} ist geöffnet.`)}
        onWorkbookLoadError={() => {
          setFile(null);
          setStatus("Diese Arbeitsmappe ließ sich nicht öffnen.");
        }}
      />
      <div className="flex items-center justify-between gap-3">
        <p className="text-sm text-muted-foreground" aria-live="polite">
          {status}
        </p>
        <Button tone="brand" disabled={!file} onClick={importRows}>
          Zeilen importieren
        </Button>
      </div>
    </div>
  );
}

Zwei Details darin stammen aus echten Dateien. readSpreadsheet nimmt die erste Zeile mit Text als Kopfzeile. Ein Berichtsblatt mit einem Titelblock über der Tabelle bekommt also den Titel als Spaltenüberschriften. Die Tabelle im Blatt Summary des Beispiels beginnt in Zeile 5: Übergib für dieses Layout header: 4 (ab 0 gezählt) oder schick die Leute zu einem reinen Datenblatt wie Transactions. Der Helfer hat außerdem eigene Limits, 20 MB pro Datei (maxBytes) gegenüber den 50 MB des Viewers und 50.000 Zeilen pro Blatt (maxRows), und meldet die abgeschnittenen Zeilen jedes Blatts in truncated. Prüf das, bevor du jemandem sagst, dass der Import vollständig ist.

Nächster Schritt

Installier den Viewer mit npx wingo-ui@latest add excel-viewer; er bringt die Spreadsheet-Helfer und seine anderen Abhängigkeiten mit, und csv-viewer installierst du genauso. Alle drei gehören zu Wingo UI Pro (Preise). Die Doku zum Excel Viewer enthält den Playground mit dem Beispielbericht und alle Props. Weitere Guides zu einzelnen Komponenten findest du in der Kategorie Komponenten-Guides und im Guide zu React-Formularkomponenten.

Häufige Fragen

Wie zeige ich eine Excel-Datei in React an?

Lade die .xlsx als Bytes, entpacke sie, lies das XML für Blatt, Styles und Shared Strings und zeichne die Zellen mit einem virtualisierten Grid. Eine Komponente wie der Excel Viewer von Wingo UI erledigt das mit einem einzigen src-Prop: einer URL vom selben Origin, einer URL mit CORS oder einer blob:-URL.

Kann ein React Excel Viewer alte .xls-Dateien öffnen?

Der Excel Viewer öffnet .xlsx, .xlsm, .csv und .tsv. Eine alte .xls ist ein anderes Binärformat, deshalb zeigt der Viewer einen Hinweis, die Datei in Excel als .xlsx zu speichern, und ruft onWorkbookLoadError auf.

Berechnet der Viewer Formeln neu?

Nein. Er zeigt die Werte, die Excel in der Datei gespeichert hat, und die Formel der aktiven Zelle in der Bearbeitungsleiste. Hat ein Tool die Datei geschrieben, ohne sie je zu berechnen, zeigen diese Zellen, was in der Datei steht.

Wird die Excel-Datei auf einen Server hochgeladen?

Nein. Eine Datei, die jemand im Viewer öffnet oder per Drag and Drop darauf zieht, wird im Browser gelesen, und onWorkbookUpload gibt dir das File-Objekt, falls du es speichern willst. Eine src-URL lädt der Browser wie jede andere Anfrage.

Wie zeige ich eine große CSV-Datei in React an?

Nimm einen Viewer, der die Datei stückweise liest und die Zeilen virtualisiert. Der CSV Viewer von Wingo UI erkennt Trennzeichen, Kodierung und Kopfzeile, nimmt standardmäßig Dateien bis 100 MB an und behält bis zu 1.000.000 Zeilen.