# Excel Viewer

> 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.

- Type: React component (Media)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add excel-viewer`
- Docs: https://wingo-ui.com/components/excel-viewer

## Interaction

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.

## Installation

```bash
npx wingo-ui@latest add excel-viewer
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/excel-viewer` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/excel-viewer.tsx`

npm dependencies: `npm i @tanstack/react-virtual fflate lucide-react`

Wingo UI dependencies (installed automatically):

- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu) ([Markdown](https://wingo-ui.com/components/dropdown-menu.md))
- [Popover](https://wingo-ui.com/components/popover) ([Markdown](https://wingo-ui.com/components/popover.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [Spreadsheet](https://wingo-ui.com/components/spreadsheet) ([Markdown](https://wingo-ui.com/components/spreadsheet.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src?` | `string` | `"/demo/q3-sales-report.xlsx"` | URL 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). |
| `fileName?` | `string` | `""` | Name 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. |
| `defaultSheet?` | `string` | `""` | The sheet it opens on, by name. Empty opens the sheet the workbook was saved on. Use sheet and onSheetChange to control it. |
| `defaultZoom?` | `number \| "fit-width"` | `1` | 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. |
| `defaultGridlines?` | `boolean` | `true` | On, 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. |
| `defaultFormulas?` | `boolean` | `false` | Opens 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. |
| `defaultDarkCells?` | `boolean` | `false` | Opens 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. |
| `sortable?` | `boolean` | `true` | The 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. |
| `resizable?` | `boolean` | `true` | Drag a column or row heading edge to resize it, double-click a column edge to fit its content. View only. |
| `maxFileSize?` | `number` | `"52428800"` | Bytes: 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. |
| `locale?` | `string` | `"en-US"` | Locale 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). |
| `variant?` | `"surface" \| "outline" \| "plain"` | `"surface"` | surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Corner radius of the frame: 0, 12, 16 or 24px. |
| `selectionColor?` | `string` | `"#217346"` | Outline 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. |
| `highlightColor?` | `string` | `"rgba(250, 204, 21, 0.4)"` | Fill of every search hit on the sheet. Keep it translucent so the cell stays readable. Also set as --excel-viewer-highlight on the frame. |
| `activeHighlightColor?` | `string` | `"rgba(249, 115, 22, 0.55)"` | Fill of the current search hit (--excel-viewer-active-highlight). |
| `showToolbar?` | `boolean` | `true` | The toolbar with zoom, search, view switches and file actions. |
| `showFormulaBar?` | `boolean` | `true` | The bar with the name box (address, go to) and the formula or value of the active cell. |
| `showSheetTabs?` | `boolean` | `true` | The sheet tabs at the bottom, with the list of sheets and, on a wide viewer, the sum, average and count of a selected range. |
| `showHeadings?` | `boolean` | `true` | The A B C column and 1 2 3 row headings. |
| `showSearch?` | `boolean` | `true` | The search button, and Ctrl+F / ⌘F inside the viewer. |
| `showGridlines?` | `boolean` | `true` | The gridlines switch in the toolbar (the ⋯ menu when narrow). |
| `showFormulas?` | `boolean` | `true` | The show formulas switch in the toolbar (the ⋯ menu when narrow). |
| `showDarkCells?` | `boolean` | `true` | The dark cells switch in the toolbar (the ⋯ menu when narrow). |
| `showDownload?` | `boolean` | `true` | The download button (in the ⋯ menu when narrow). It saves the original file. |
| `showUpload?` | `boolean` | `true` | Open a workbook in the ⋯ menu and dropping an .xlsx or .csv onto the viewer. The file opens locally; onWorkbookUpload hands it to you. |
| `height?` | `number \| string` | `640` | Height of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane. |
| `sheet?` | `string` |  | Controls the sheet shown, by name. Pair it with onSheetChange. |
| `onSheetChange?` | `(sheet: string) => void` |  | Called with the sheet name when a tab, the sheets menu, a search hit or ref.goTo switches sheets. |
| `zoomLevels?` | `number[]` | `"[0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]"` | Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits for pinch and Ctrl / ⌘ + scroll too. |
| `toolbarActions?` | `ReactNode` |  | Your own buttons at the end of the toolbar, before the ⋯ menu: share, import, approve. |
| `ref?` | `Ref<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) => void` |  | Called 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) => void` |  | Called 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) => void` |  | Called when a workbook cannot be fetched or parsed, or is an old .xls. The viewer shows the error state. |
| `onWorkbookUpload?` | `(file: File) => void` |  | Called with the File someone opened or dropped, as the viewer starts showing it. |
| `labels?` | `Partial<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). |
| `classNames?` | `Partial<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. |
| `className?` | `string` |  | Extra classes for the frame, merged last. Other div props are forwarded to it. |

## Parts

### ExcelViewerHandle (type)

What 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 (type)

What onCellSelect receives: sheet, address, range (1-based startRow, startColumn, endRow, endColumn) and cell (address, row, column, value, text, formula, note, link).

### ExcelViewerWorkbook (type)

What onWorkbookLoadSuccess receives: fileName, sheets (ExcelViewerSheetInfo[]), definedNames ({ name, ref }[]) and properties (title, creator, lastModifiedBy, created, modified, company).

### ExcelViewerSheetInfo (type)

A sheet of the workbook: name, index, hidden, rowCount and columnCount (the used range).

### ExcelViewerCellValue (type)

A raw cell value: string, number (dates are Excel serial numbers), boolean or null.

### ExcelViewerZoom (type)

A scale or "fit-width".

### ExcelViewerLabels (type)

The shape of labels: every string the viewer renders.

### DEFAULT_EXCEL_VIEWER_LABELS (constant)

The 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.

## See also

- [CSV Viewer](https://wingo-ui.com/components/csv-viewer) ([Markdown](https://wingo-ui.com/components/csv-viewer.md))
- [DOCX Viewer](https://wingo-ui.com/components/docx-viewer) ([Markdown](https://wingo-ui.com/components/docx-viewer.md))
- [PDF Viewer](https://wingo-ui.com/components/pdf-viewer) ([Markdown](https://wingo-ui.com/components/pdf-viewer.md))
- [CSV Import](https://wingo-ui.com/components/csv-import) ([Markdown](https://wingo-ui.com/components/csv-import.md))
- [Spreadsheet](https://wingo-ui.com/components/spreadsheet) ([Markdown](https://wingo-ui.com/components/spreadsheet.md))
- [Data Table](https://wingo-ui.com/components/data-table) ([Markdown](https://wingo-ui.com/components/data-table.md))

---

Canonical: https://wingo-ui.com/components/excel-viewer
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt
