Excel Viewer React component for Tailwind CSS v4
v1.0.0Added in 1.4.0
A React Excel viewer for .xlsx and CSV files with real cell styles, number formats, frozen panes, sheet tabs, a formula bar, sort and search.
Scroll the sheet both ways: only the rows and columns in view are drawn, so tens of thousands of rows stay smooth, and the A B C / 1 2 3 headings and the file's frozen rows and columns stay put. Cells keep the workbook's look: fonts, fills, borders, alignment, wrapping, merged cells, column widths and row heights, hidden rows and columns, number formats (currency, percent, dates through Intl and the locale), conditional formats (color scales, data bars, icon sets, highlight rules), Excel table styles, images and charts. Click a cell to select it, Shift+click or drag for a range, click a heading for a whole column or row; on touch, tap a cell. The keyboard works like Excel's: arrows, Tab, Enter, Home / End, Page Up / Down, Ctrl / ⌘ + arrows jump to the edge of the data, Shift extends, Ctrl / ⌘ + A selects all, Ctrl / ⌘ + C copies as tab separated text. The formula bar shows the address and the formula or value of the active cell; type an address, a range like Team!A2:C9 or a defined name in its box and press Enter to go there. Each column heading has a menu (Alt+Down) to sort A to Z or Z to A in the view only (blank cells stay last, totals rows stay at the bottom) and to clear the sort; drag a heading edge to resize, double-click it to fit. Search opens from the toolbar or with Ctrl+F / ⌘F inside the viewer and looks through every sheet: the counter reads 2 of 6 and Enter / Shift+Enter jump between hits, switching sheets as needed. Sheet tabs sit at the bottom and scroll sideways; hidden sheets are left out and the ☰ menu lists them all. The toolbar zooms (- / + or a percentage, Fit width), turns gridlines, formulas and dark cells on or off and downloads the file; below 720px of width these move into the ⋯ menu, which also opens another .xlsx or .csv (or drop one onto the viewer). Pinch with two fingers, or Ctrl / ⌘ + scroll, to zoom around that point. Menus become bottom sheets on phones.
Excel Viewer is a Pro React component in the React media components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add excel-viewer, together with Button, Dropdown Menu, Popover, Tooltip, useControllableState and 2 more and the npm packages @tanstack/react-virtual, fflate and lucide-react.
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
npx wingo-ui@latest add excel-viewerExcel Viewer 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 ExcelViewer from @/components/ui/excel-viewer.
import { ExcelViewer } from "@/components/ui/excel-viewer"
export function SalesReportPreview() {
return (
<ExcelViewer
src="/demo/q3-sales-report.xlsx"
fileName="Q3 2026 sales report.xlsx"
height="80dvh"
onCellSelect={({ address, cell }) => console.log(address, cell.text)}
/>
)
}Props
srcdefault"/demo/q3-sales-report.xlsx"stringURL of the .xlsx or .csv: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-workbook state. The playground value is the sample sales report (3 sheets, 2,000 orders).
fileNamedefault""stringName used for downloads, in the toolbar and in the grid's accessible label. Falls back to the last part of src; an uploaded file keeps its own name.
defaultSheetdefault""stringThe sheet it opens on, by name. Empty opens the sheet the workbook was saved on. Use sheet and onSheetChange to control it.
defaultZoomdefault1number | "fit-width"The zoom each workbook opens at: a scale (1 is 100%), or "fit-width", which fits the used columns to the viewer. The playground slider sets the scale.
defaultGridlinesdefaulttruebooleanOn, each sheet shows gridlines the way the file says (a sheet saved without them stays clean). Off hides them everywhere. The toolbar switch changes the current sheet.
defaultFormulasdefaultfalsebooleanOpens with formulas shown in the cells instead of their values, like Excel's Show Formulas. Values are the ones saved in the file; nothing is recalculated.
defaultDarkCellsdefaultfalsebooleanOpens with dark cells for reading at night: white and light fills turn dark, text turns light, strong colors stay. Cells are white otherwise, in both themes.
sortabledefaulttruebooleanThe menu on each column heading: sort A to Z, Z to A and clear. Sorting reorders the view only; the file and the download stay as they were.
resizabledefaulttruebooleanDrag a column or row heading edge to resize it, double-click a column edge to fit its content. View only.
maxFileSizedefault"52428800"numberBytes: 50 MB by default. A bigger file shows the file too large state with a download link instead of being parsed. The playground offers 100 KB, smaller than the sample, to show it.
localedefault"en-US"stringLocale for numbers, currency and dates: decimal and thousands separators, month and day names, and the short date of Excel's system date format. Unset, it follows the UIProvider locale, then the browser's (en-US here).
variantdefault"surface""surface" | "outline" | "plain"surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
radiusdefault"md""none" | "sm" | "md" | "lg"Corner radius of the frame: 0, 12, 16 or 24px.
selectionColordefault"#217346"stringOutline of the selection, the tint of a selected range and the mark on selected headings. Any CSS color; also set as --excel-viewer-selection on the frame.
highlightColordefault"rgba(250, 204, 21, 0.4)"stringFill of every search hit on the sheet. Keep it translucent so the cell stays readable. Also set as --excel-viewer-highlight on the frame.
activeHighlightColordefault"rgba(249, 115, 22, 0.55)"stringFill of the current search hit (--excel-viewer-active-highlight).
showToolbardefaulttruebooleanThe toolbar with zoom, search, view switches and file actions.
showFormulaBardefaulttruebooleanThe bar with the name box (address, go to) and the formula or value of the active cell.
showSheetTabsdefaulttruebooleanThe sheet tabs at the bottom, with the list of sheets and, on a wide viewer, the sum, average and count of a selected range.
showHeadingsdefaulttruebooleanThe A B C column and 1 2 3 row headings.
showSearchdefaulttruebooleanThe search button, and Ctrl+F / ⌘F inside the viewer.
showGridlinesdefaulttruebooleanThe gridlines switch in the toolbar (the ⋯ menu when narrow).
showFormulasdefaulttruebooleanThe show formulas switch in the toolbar (the ⋯ menu when narrow).
showDarkCellsdefaulttruebooleanThe dark cells switch in the toolbar (the ⋯ menu when narrow).
showDownloaddefaulttruebooleanThe download button (in the ⋯ menu when narrow). It saves the original file.
showUploaddefaulttruebooleanOpen a workbook in the ⋯ menu and dropping an .xlsx or .csv onto the viewer. The file opens locally; onWorkbookUpload hands it to you.
heightdefault640number | stringHeight of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
sheetstringControls the sheet shown, by name. Pair it with onSheetChange.
onSheetChange(sheet: string) => voidCalled with the sheet name when a tab, the sheets menu, a search hit or ref.goTo switches sheets.
zoomLevelsdefault"[0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]"number[]Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits for pinch and Ctrl / ⌘ + scroll too.
toolbarActionsReactNodeYour own buttons at the end of the toolbar, before the ⋯ menu: share, import, approve.
refRef<ExcelViewerHandle> (a useRef object or an (handle) => void callback)selectSheet(name or index), goTo("B12" | "Team!A2:C9" | defined name, options?), getSelection(), getWorkbook(), clearSort() and getViewportElement().
onCellSelect(selection: ExcelViewerSelection) => voidCalled when the selection moves, with the sheet, the address (B12 or A1:D20), the range and the active cell's value, shown text, formula, note and link.
onWorkbookLoadSuccess(workbook: ExcelViewerWorkbook) => voidCalled when a workbook is ready, with its file name, sheets (hidden ones flagged, with their used size), defined names and document properties (title, author, dates, company).
onWorkbookLoadError(error: unknown) => voidCalled when a workbook cannot be fetched or parsed, or is an old .xls. The viewer shows the error state.
onWorkbookUpload(file: File) => voidCalled with the File someone opened or dropped, as the viewer starts showing it.
labelsPartial<ExcelViewerLabels>Every string, English by default (DEFAULT_EXCEL_VIEWER_LABELS): workbook, grid, zoomIn, zoomOut, zoomLevel, fitWidth, search, searchPlaceholder, searching, noResults, results(active, total), previousResult, nextResult, clearSearch, moreActions, gridlines, formulas, darkCells, download, upload, loading, error, errorDescription, unsupported, tooLarge, tooLargeDescription(limit), emptyTitle, emptyDescription, dropHere, nameBox, formulaBar, copy, copied, sheets, sheetTabs, selectAll, columnHeader(column), rowHeader(row), columnMenu(column), sortAscending, sortDescending, clearSort, copyColumn, sorted(column, direction), resizeColumn(column), note, openLink, chart, sum, average, count, cellLabel(address, text).
classNamesPartial<Record<"toolbar" | "formulaBar" | "viewport" | "header" | "cell" | "tabs" | "tab" | "state", string>>Extra classes for the toolbar, the formula bar, the scrolling viewport, each heading, each cell, the tab strip, each tab and the loading / empty / error states.
classNamestringExtra classes for the frame, merged last. Other div props are forwarded to it.
Parts
ExcelViewerHandle
typeWhat the ref gets: selectSheet(sheet), goTo(ref, { behavior }?) which selects and scrolls to "B12", "A1:D20", "Team!A2", "'Q3 Sales'!B2:C9" or a defined name and returns false when it does not exist, getSelection(), getWorkbook(), clearSort() and getViewportElement().
ExcelViewerSelection
typeWhat onCellSelect receives: sheet, address, range (1-based startRow, startColumn, endRow, endColumn) and cell (address, row, column, value, text, formula, note, link).
ExcelViewerWorkbook
typeWhat onWorkbookLoadSuccess receives: fileName, sheets (ExcelViewerSheetInfo[]), definedNames ({ name, ref }[]) and properties (title, creator, lastModifiedBy, created, modified, company).
ExcelViewerSheetInfo
typeA sheet of the workbook: name, index, hidden, rowCount and columnCount (the used range).
ExcelViewerCellValue
typeA raw cell value: string, number (dates are Excel serial numbers), boolean or null.
ExcelViewerZoom
typeA scale or "fit-width".
ExcelViewerLabels
typeThe shape of labels: every string the viewer renders.
DEFAULT_EXCEL_VIEWER_LABELS
constantThe English labels. Spread it to translate a few strings.
Examples
Selected cell outside the viewer
onCellSelect reports the address, the shown text, the raw value and the formula of the active cell.
Jump to a range
ref.goTo selects a range on any sheet and scrolls it into view, here the Q3 totals and the last of 2,000 orders.
Sort 2,000 orders
Open a column heading's menu (or press Alt+Down) to sort the Transactions sheet by revenue, date or rep. Only the view changes.
Your own toolbar actions
toolbarActions adds Share and Mark reviewed; the view switches fold into the ⋯ menu when the toolbar runs out of room.
On a phone
The grid stays a grid with sticky headings, tap selects a cell and shows it in the formula bar, menus open as bottom sheets.
German locale, dark cells
locale="de-DE" switches the decimal and thousands separators and the month names; defaultDarkCells darkens the light fills.
Empty, open a file
Without src the viewer asks for a workbook: pick an .xlsx or .csv or drop it onto the frame.
File too large
maxFileSize={100 * 1024} refuses the 145 KB sample before parsing and offers the download instead.
Dependencies
Files
- components/ui/excel-viewer.tsx
FAQ
Is the React Excel Viewer component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install Excel Viewer?
Run npx wingo-ui@latest add excel-viewer. It also adds the Wingo UI items it builds on (Button, Dropdown Menu, Popover, Tooltip, useControllableState and 2 more) and the npm packages @tanstack/react-virtual, fflate and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/excel-viewer.
How does Excel Viewer behave on phones?
Menus become bottom sheets on phones.
See also
Used in
More React media components
Articles using this component
- React Excel Viewer: Show .xlsx Files With Their Real Styles
Component guides10 min read
New components by email
New posts, product news and occasional offers from Wingo UI. We count clicks to keep it relevant.