CSV Viewer React component for Tailwind CSS v4
v1.0.0Added in 1.4.0
A React CSV viewer for large CSV and TSV files: typed columns, sort, filters, search, selection with copy, frozen columns and zoom.
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.
CSV 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 csv-viewer, together with Button, Checkbox, Dropdown Menu, Popover, Tooltip and 2 more and the npm packages @tanstack/react-virtual 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 csv-viewerCSV 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 CsvViewer from @/components/ui/csv-viewer.
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
srcdefault"/demo/northwind-q3-orders.csv"stringURL 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.
datadefault""stringThe delimited text itself, instead of src. It wins over src while it is not empty.
fileNamedefault""stringName 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.
delimiterdefault"auto""auto" | "comma" | "semicolon" | "tab" | "pipe"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.
encodingdefault"auto""auto" | "utf-8" | "utf-16le" | "utf-16be" | "windows-1252" | "windows-1250"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.
headerdefault"auto""auto" | "first-row" | "none"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.
defaultZoomdefault1numberThe zoom each file opens at, 1 is 100%. It scales text, rows and columns together.
defaultWrapTextdefaultfalsebooleanOpens with long values wrapped onto up to six lines (rows grow to fit) instead of cut off on one line.
defaultRowNumbersdefaulttruebooleanOpens with the row number column. Numbers are each row's place in the file, so they stay with the row when it is sorted.
defaultFormatValuesdefaulttruebooleanOpens with numbers and dates formatted for the locale (1,234.50, Jul 14, 2026). Off shows every value as the file writes it.
defaultFrozenColumnsdefault0numberHow many columns from the left stay put while scrolling sideways. The column panel freezes or unfreezes up to any column.
sortabledefaulttruebooleanSort 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.
filterabledefaulttruebooleanFilter in the column panel: values that contain a text, and a checklist of the values when a column has 200 or fewer different ones.
resizabledefaulttruebooleanDrag a column header edge to resize it, double-click it to fit the content. Fit width is in the column panel too (touch screens).
maxFileSizedefault104857600numberBytes: 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.
maxRowsdefault1000000numberRows kept after the header. The rest is left out and the status bar says First 1,000,000 rows.
localedefault"en-US"stringLocale 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.
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"#2563eb"stringOutline 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.
highlightColordefault"rgba(250, 204, 21, 0.4)"stringFill of every search hit. Keep it translucent so the cell stays readable. Also set as --csv-viewer-highlight on the frame.
activeHighlightColordefault"rgba(249, 115, 22, 0.55)"stringFill of the current search hit (--csv-viewer-active-highlight).
showToolbardefaulttruebooleanThe toolbar with zoom, search, view switches, columns and file actions.
showDetailBardefaulttruebooleanThe bar with the address box (go to) and the full value of the active cell.
showStatusBardefaulttruebooleanThe bar under the grid: rows and columns, filtered rows, the totals of a selection, and the delimiter and encoding switches.
showSearchdefaulttruebooleanThe search button, and Ctrl+F / ⌘F inside the viewer.
showViewSwitchesdefaulttruebooleanThe header row, wrap text, row numbers and format switches (toolbar buttons when wide, the ⋯ menu when narrow).
showColumnsMenudefaulttruebooleanThe columns menu that shows or hides columns.
showDownloaddefaulttruebooleanThe download button (in the ⋯ menu when narrow). It saves the original file, bytes unchanged.
showUploaddefaulttruebooleanOpen a file in the ⋯ menu and dropping a file onto the viewer. The file opens locally; onFileUpload hands it to you.
heightdefault640number | stringHeight of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
zoomLevelsdefault"[0.5, 0.75, 1, 1.25, 1.5, 2]"number[]Steps of the zoom menu and the - / + buttons. The first and last are the limits for pinch and Ctrl / ⌘ + scroll too.
toolbarActionsReactNodeYour own buttons at the end of the toolbar, before the ⋯ menu: share, import, approve.
refRef<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) => voidCalled 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) => voidCalled 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) => voidCalled 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) => voidCalled with the File someone opened or dropped, as the viewer starts reading it.
onSortChange(sort: CsvViewerSort | null) => voidCalled when a column is sorted ({ column, columnName, direction }) or the sort is cleared (null).
labelsPartial<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).
classNamesPartial<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.
classNamestringExtra classes for the frame, merged last. Other div props are forwarded to it.
Parts
CsvViewerHandle
typeWhat 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
typeWhat onCellSelect receives: address, range (1-based startRow, startColumn, endRow, endColumn), rowCount, columnCount and cell (address, row, column, columnName, type, value, text).
CsvViewerFileInfo
typeWhat onFileLoadSuccess and getData() return: fileName, rowCount, columnCount, delimiter, encoding (null for data), header, headers, columnTypes, truncated and bytes.
CsvViewerSort
typeWhat onSortChange receives: column (0-based), columnName and direction.
CsvViewerColumnType
type"number", "date", "boolean" or "text": what a column was recognized as.
CsvViewerLabels
typeThe shape of labels: every string the viewer renders.
DEFAULT_CSV_VIEWER_LABELS
constantThe 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.
Dependencies
Files
- components/ui/csv-viewer.tsx
FAQ
Is the React CSV Viewer component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install CSV Viewer?
Run npx wingo-ui@latest add csv-viewer. It also adds the Wingo UI items it builds on (Button, Checkbox, Dropdown Menu, Popover, Tooltip and 2 more) and the npm packages @tanstack/react-virtual and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/csv-viewer.
How does CSV Viewer behave on phones?
Menus and panels 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.