# CSV Viewer

> A React CSV viewer for large CSV and TSV files: typed columns, sort, filters, search, selection with copy, frozen columns and zoom.

- 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 csv-viewer`
- Docs: https://wingo-ui.com/components/csv-viewer

## Interaction

The file is read in the browser in small slices, so the first rows show while a big file is still loading and the page never freezes; only the rows and columns in view are drawn, so 200,000 rows scroll smoothly. The delimiter (comma, semicolon, tab or pipe), the text encoding (UTF-8 with or without BOM, UTF-16, Windows-1252) and the header row are detected; change any of them from the status bar or the ⋯ menu. Columns without a header are named A, B, C. Numbers, dates and true / false columns are recognized: numbers align right, numbers and dates are formatted for the locale, sorting follows the type and copies keep the original values. Click a cell, Shift+click or drag for a range, click a column header or a row number for a whole column or row; on touch, tap a cell. The keyboard works like a spreadsheet'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, Alt + drag selects text inside cells. The bar above the grid shows the address and the full value of the active cell (type an address like C120 and press Enter to go there). Each column header opens a panel (Alt+Down) to sort, filter by text or by a list of its values, fit the width, freeze the columns up to it, hide it or copy it; drag a header edge to resize, double-click it to fit. Search opens from the toolbar or with Ctrl+F / ⌘F inside the viewer: the counter reads 2 of 6 and Enter / Shift+Enter jump between hits. The status bar counts rows and columns, shows how many rows a filter keeps, and the sum, average and count of a selected range. The toolbar zooms, turns the header row, wrapped text, row numbers and formatting on or off, shows or hides columns and downloads the file; below 720px of width these move into the ⋯ menu, which also opens another file (or drop one onto the viewer). Pinch with two fingers, or Ctrl / ⌘ + scroll, to zoom around that point. Menus and panels become bottom sheets on phones.

## Installation

```bash
npx wingo-ui@latest add csv-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/csv-viewer` (needs the @wingo-ui registry with your API key in components.json)

Files:

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

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

Wingo UI dependencies (installed automatically):

- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Checkbox](https://wingo-ui.com/components/checkbox) ([Markdown](https://wingo-ui.com/components/checkbox.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))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

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

export function OrdersPreview() {
  return (
    <CsvViewer
      src="/demo/northwind-q3-orders.csv"
      height="80dvh"
      defaultFrozenColumns={1}
      onCellSelect={({ address, cell }) => console.log(address, cell.value)}
    />
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src?` | `string` | `"/demo/northwind-q3-orders.csv"` | URL of the .csv, .tsv or .txt: same origin, a CORS-enabled URL or a blob: URL. Empty (and no data) shows the open-a-file state. The playground value is 5,000 sample orders. |
| `data?` | `string` | `""` | The delimited text itself, instead of src. It wins over src while it is not empty. |
| `fileName?` | `string` | `""` | Name used for downloads, in the toolbar and in the grid's accessible label. Falls back to the last part of src (data.csv for data); an opened file keeps its own name. |
| `delimiter?` | `"auto" \| "comma" \| "semicolon" \| "tab" \| "pipe"` | `"auto"` | auto detects it from the first rows, quotes respected (a .tsv name prefers tab). The status bar and the ⋯ menu switch it for the file in view, or back to detection. |
| `encoding?` | `"auto" \| "utf-8" \| "utf-16le" \| "utf-16be" \| "windows-1252" \| "windows-1250"` | `"auto"` | auto reads a byte order mark, then UTF-16 by its zero bytes, then UTF-8 when the bytes are valid UTF-8, else Windows-1252. Switch it from the status bar when accents look wrong. |
| `header?` | `"auto" \| "first-row" \| "none"` | `"auto"` | Whether the first row names the columns. auto compares it with the rows under it (a text first row over numbers or dates is a header). Without one, columns are named A, B, C. |
| `defaultZoom?` | `number` | `1` | The zoom each file opens at, 1 is 100%. It scales text, rows and columns together. |
| `defaultWrapText?` | `boolean` | `false` | Opens with long values wrapped onto up to six lines (rows grow to fit) instead of cut off on one line. |
| `defaultRowNumbers?` | `boolean` | `true` | Opens with the row number column. Numbers are each row's place in the file, so they stay with the row when it is sorted. |
| `defaultFormatValues?` | `boolean` | `true` | Opens with numbers and dates formatted for the locale (1,234.50, Jul 14, 2026). Off shows every value as the file writes it. |
| `defaultFrozenColumns?` | `number` | `0` | How many columns from the left stay put while scrolling sideways. The column panel freezes or unfreezes up to any column. |
| `sortable?` | `boolean` | `true` | Sort in the column panel, by the column's type: numbers by value, dates by time, text with the locale's alphabet. Blank cells stay last. The view changes, the file does not. |
| `filterable?` | `boolean` | `true` | Filter in the column panel: values that contain a text, and a checklist of the values when a column has 200 or fewer different ones. |
| `resizable?` | `boolean` | `true` | Drag a column header edge to resize it, double-click it to fit the content. Fit width is in the column panel too (touch screens). |
| `maxFileSize?` | `number` | `104857600` | Bytes: 100 MB by default. A bigger file shows the file too large state with a download link instead of being read. Slide it under 690 KB to see it with the sample. |
| `maxRows?` | `number` | `1000000` | Rows kept after the header. The rest is left out and the status bar says First 1,000,000 rows. |
| `locale?` | `string` | `"en-US"` | Locale for formatted numbers and dates and for text sorting. Unset, it follows the UIProvider locale, then the browser's (en-US here). The file's own decimal mark is detected separately. |
| `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` | `"#2563eb"` | Outline of the selection, the tint of a selected range and the mark on selected headers. Any CSS color; also set as --csv-viewer-selection on the frame. |
| `highlightColor?` | `string` | `"rgba(250, 204, 21, 0.4)"` | Fill of every search hit. Keep it translucent so the cell stays readable. Also set as --csv-viewer-highlight on the frame. |
| `activeHighlightColor?` | `string` | `"rgba(249, 115, 22, 0.55)"` | Fill of the current search hit (--csv-viewer-active-highlight). |
| `showToolbar?` | `boolean` | `true` | The toolbar with zoom, search, view switches, columns and file actions. |
| `showDetailBar?` | `boolean` | `true` | The bar with the address box (go to) and the full value of the active cell. |
| `showStatusBar?` | `boolean` | `true` | The bar under the grid: rows and columns, filtered rows, the totals of a selection, and the delimiter and encoding switches. |
| `showSearch?` | `boolean` | `true` | The search button, and Ctrl+F / ⌘F inside the viewer. |
| `showViewSwitches?` | `boolean` | `true` | The header row, wrap text, row numbers and format switches (toolbar buttons when wide, the ⋯ menu when narrow). |
| `showColumnsMenu?` | `boolean` | `true` | The columns menu that shows or hides columns. |
| `showDownload?` | `boolean` | `true` | The download button (in the ⋯ menu when narrow). It saves the original file, bytes unchanged. |
| `showUpload?` | `boolean` | `true` | Open a file in the ⋯ menu and dropping a file onto the viewer. The file opens locally; onFileUpload 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. |
| `zoomLevels?` | `number[]` | `"[0.5, 0.75, 1, 1.25, 1.5, 2]"` | Steps of the zoom menu and the - / + buttons. The first and last are the 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<CsvViewerHandle> (a useRef object or an (handle) => void callback)` |  | goTo("C120" \| "B12:D20" \| "120" \| { row, column }, options?), getSelection(), getData(), getRows({ start, end, view }?), clearSort(), clearFilters() and getViewportElement(). |
| `onCellSelect?` | `(selection: CsvViewerSelection) => void` |  | Called when the selection moves, with the address (B12 or B12:D20), the range and the active cell's column, type, raw value and shown text. |
| `onFileLoadSuccess?` | `(file: CsvViewerFileInfo) => void` |  | Called once a file is read to the end, and again after the delimiter, encoding or header row changes: rows, columns, delimiter, encoding, header, column names and types. |
| `onFileLoadError?` | `(error: unknown) => void` |  | Called when a file cannot be fetched or read, is too large, empty, binary or an Excel workbook. The viewer shows the matching state. |
| `onFileUpload?` | `(file: File) => void` |  | Called with the File someone opened or dropped, as the viewer starts reading it. |
| `onSortChange?` | `(sort: CsvViewerSort \| null) => void` |  | Called when a column is sorted ({ column, columnName, direction }) or the sort is cleared (null). |
| `labels?` | `Partial<CsvViewerLabels>` |  | Every string, English by default (DEFAULT_CSV_VIEWER_LABELS): toolbar, search, column panel, states, status bar and accessible names, including results(active, total), loadingProgress(percent), sortAscending(type), sortDescending(type), columnTypes and cellLabel(address, column, text). |
| `classNames?` | `Partial<Record<"toolbar" \| "detailBar" \| "viewport" \| "header" \| "row" \| "cell" \| "statusBar" \| "columnPanel" \| "state", string>>` |  | Extra classes for the toolbar, the detail bar, the scrolling viewport, each header and row number, each row, each cell, the status bar, the column panel and the loading / empty / error states. |
| `className?` | `string` |  | Extra classes for the frame, merged last. Other div props are forwarded to it. |

## Parts

### CsvViewerHandle (type)

What the ref gets: goTo(target, { behavior }?) which selects and scrolls to "C120", "B12:D20", a row number or { row, column } and returns false when the row is filtered out or missing, getSelection(), getData(), getRows(options?), clearSort(), clearFilters() and getViewportElement().

### CsvViewerSelection (type)

What onCellSelect receives: address, range (1-based startRow, startColumn, endRow, endColumn), rowCount, columnCount and cell (address, row, column, columnName, type, value, text).

### CsvViewerFileInfo (type)

What onFileLoadSuccess and getData() return: fileName, rowCount, columnCount, delimiter, encoding (null for data), header, headers, columnTypes, truncated and bytes.

### CsvViewerSort (type)

What onSortChange receives: column (0-based), columnName and direction.

### CsvViewerColumnType (type)

"number", "date", "boolean" or "text": what a column was recognized as.

### CsvViewerLabels (type)

The shape of labels: every string the viewer renders.

### DEFAULT_CSV_VIEWER_LABELS (constant)

The English labels. Spread it to translate a few strings.

## Examples

- **Selected cell outside the viewer**: onCellSelect reports the address, the column and its type, the shown text and the value as the file has it.
- **Sort and filter 5,000 orders**: Open a column header's panel (or press Alt+Down) to sort by Total, keep only Delivered orders or filter customers by text. Order ID stays frozen.
- **Semicolons and German numbers**: A European export: ";" between values, 58.721,62 decimals and 31.07.2026 dates are detected; locale="de-DE" formats them back.
- **Tab separated, your own actions**: A .tsv of the sales team with wrapped notes; toolbarActions adds Share and Mark reviewed, the switches fold into the ⋯ menu when narrow.
- **On a phone**: The grid stays a grid with sticky headers and a frozen first column; tap a cell to see it in the bar above, panels open as bottom sheets.
- **No header row**: Text passed through data with no header: the first row is kept as data and the columns are named A to F, still typed and sortable.
- **Empty, open a file**: Without src or data the viewer asks for a file: pick a .csv, .tsv or .txt or drop it onto the frame.
- **File too large**: maxFileSize={100 * 1024} refuses the 690 KB sample before reading it and offers the download instead.

## See also

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

---

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