Skip to content
WingoUI
ComponentsTemplatesDocsPricingAI agentsBlogChangelogContact
Components
Buttons & Actions
ButtonButton GroupCopy ButtonDelete ButtonTheme ToggleToggleToggle Group
Inputs
Avatar UploadCalendarCheckboxColor PickerComboboxCountry SelectCron PickerCurrency InputDate PickerDate Range PickerDate Time PickerDuration PickerEmail InputEmoji PickerFile UploadFilter BuilderInputInput GroupListboxMasked InputMention InputMonth PickerMulti SelectNumber InputOTP InputPassword InputPhone InputRadio GroupRatingSearch InputSegmented ControlSelectSignature PadSliderSwitchTag InputTextareaTime PickerTimezone SelectTree Select
Forms
Address InputBooking WidgetCSV ImportFieldForm WizardInline EditInvoice line itemsRich Text EditorSchema Builder
Navigation
Back To TopBounce SidebarBreadcrumbCommand MenuGlobal SearchGooey NavHook SidebarNav MenuNav TabsPaginationProximity SidebarScroll ProgressSidebarStepsTable Of ContentsTabsTopbarUser MenuWorkspace Switcher
Overlays
Alert DialogContext MenuDialogDrawerDropdown MenuFamily DrawerHover CardPopoverShare DialogSheetShortcuts DialogTooltipTour
Feedback
AlertBannerCookie ConsentEmoji ReactionEmpty StateNotification BellNotification CenterProgressRoute ProgressSetup ChecklistSkeletonSpinnerToast
Data Display
Approval FlowAvatarBadgeCalendar ViewCode BlockComment ThreadContact cardCountdownDescription ListDiff ViewerFile ListFile managerFolderGanttJSON ViewerKbdLog ViewerMarkdownPresenceSchedulerTagTimelineTree View
Tables & Lists
Audit LogData TableDeal PipelineEditable GridKanbanListMembers tablePermissions MatrixTableTask ListVirtual List
Charts & Stats
Animated CounterArea chartBar chartDonut chartFunnel chartGaugeGitHub ActivityHeatmap calendarLeaderboardLine chartRadar chartRadial barSparklineStat CardTrackerTrend badge
Layout
AccordionApp ShellCardCollapsibleDetail LayoutEntity HeaderPage HeaderScroll AreaSeparatorSettings LayoutSplit ViewToolbar
Media
Audio PlayerCarouselCSV ViewerDOCX EditorDOCX ViewerExcel ViewerFile SystemImage compareImage CropperImage GalleryImage LightboxLocation MapPDF ViewerPowerPoint ViewerQR CodeStep PlayerVideo Player
AI Kit
Agent Status CardChat MessageChat ThreadChat WidgetConversation ListFluid OrbGrid RevealMatrix OrbModel PickerPrompt InputReasoning IndicatorRule BuilderSuggestion ChipsTool Call TimelineUsage MeterVoice InputWorkflow Canvas
Text & Effects
Background PatternGravity LettersMarqueeTerminalText AnimateText Rotate
Mobile
Action SheetBottom Tab BarFABHaptic ButtonHero HeaderInstall PromptLarge Title HeaderNotification BannerOnboarding CarouselPicker WheelPull To RefreshSlide To ConfirmSticky CTA BarSwipe DeckSwipeable Tabs
Commerce
Cart drawerCategory pickerCheckout stepsCoupon inputFavorite buttonFilter panelListing cardListing gridOrder trackerPricePrice rangePricing tableProduct galleryQuantity stepperReviewsSeller card
Marketing Sections
App Download SectionBlog Cards SectionCTA SectionFAQ SectionFeature GridFeature ShowcaseHero SectionIntegrations SectionLogo CloudMarketing FooterMarketing HeaderMarketing SectionNewsletter SectionPricing SectionStats SectionSteps SectionTeam SectionTestimonials SectionTimeline SectionVideo Section
Blocks
Admin Dashboard PageAdmin ShellAI Chat PageAPI Keys PageAutomation Builder PageCheckout PageCRM Contact PageCRM Pipeline PageError PagesInbox PageInvoice PageKPI DashboardListing Detail PageLogin PageMarketplace Home PageMarketplace Search PageMarketplace ShellMobile App HomeOnboarding FlowOrder History PagePost Listing WizardPricing PageProfile PageRegister PageSettings PageUsers Admin Page
Templates
About PageAcademy PageAccessibility PageAffiliate PageAgency PageAI Product PageAppointment Booking PageBlog PageBlog Post PageBug Bounty PageCareers PageChangelog PageCommunity PageCompare PageContact PageCustomer Story PageCustomers PageDemo Booking PageDevelopers PageDocs Home PageDownload PageEnterprise PageEvents PageExperts PageFAQ PageFeature PageGlossary PageHelp Article PageHelp Center PageHome Services PageImpact PageIntegration Detail PageIntegrations PageJob Detail PageLanding PageLaunch PageLegal PageManifesto PagePortfolio PagePress PageProduct Tour PagePromo PageReal Estate PageReferral PageResearch Report PageRestaurant PageRoadmap PageROI Calculator PageSecurity PageSolutions PageStartups PageStatus PageStorefront PageSwitch PageTemplate Gallery PageTravel PageWaitlist PageYear in Review Page
Hooks & Utilities
AI ChatChart kitCommerceDate utilsFile exportFile typesFiltersForm validationHapticsInvoicingMotion presetsNavigationNumber formatRelative timeRomanian locationsSpreadsheetText matchTonesUIProvideruseClipboarduseConsentuseControllableStateuseCooldownuseDebounceuseKeyboardInsetuseLocaleuseLongPressuseMediaControlsuseMediaQueryuseOverflowItemsusePersistedStateuseScrollEdgesuseScrollStateuseSelectionuseShortcutuseStickToBottom
GalleryTheme

Media

CSV Viewer

Media

CSV Viewer React component for Tailwind CSS v4

CarouselDOCX Editor
Live props
Content
src
data
fileName
delimiter
encoding
header
Behavior
defaultZoom1
defaultWrapText
defaultRowNumbers
defaultFormatValues
defaultFrozenColumns0
sortable
filterable
resizable
maxFileSize104857600B
maxRows1000000
locale
Appearance
variant
radius
selectionColor
highlightColor
activeHighlightColor
Layout
showToolbar
showDetailBar
showStatusBar
showSearch
showViewSwitches
showColumnsMenu
showDownload
showUpload
height640px
Code
import { CsvViewer } from "@/components/ui/csv-viewer"

<CsvViewer />
  1. Home
  2. Components
  3. Media
  4. CSV Viewer
Pro

CSV Viewer React component for Tailwind CSS v4

v1.0.0·Added 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-viewer

CSV 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 or unlock it free with an account

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"
    string

    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.

  • datadefault ""
    string

    The delimited text itself, instead of src. It wins over src while it is not empty.

  • fileNamedefault ""
    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.

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

  • defaultZoomdefault 1
    number

    The zoom each file opens at, 1 is 100%. It scales text, rows and columns together.

  • defaultWrapTextdefault false
    boolean

    Opens with long values wrapped onto up to six lines (rows grow to fit) instead of cut off on one line.

  • defaultRowNumbersdefault true
    boolean

    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.

  • defaultFormatValuesdefault true
    boolean

    Opens with numbers and dates formatted for the locale (1,234.50, Jul 14, 2026). Off shows every value as the file writes it.

  • defaultFrozenColumnsdefault 0
    number

    How many columns from the left stay put while scrolling sideways. The column panel freezes or unfreezes up to any column.

  • sortabledefault true
    boolean

    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.

  • filterabledefault true
    boolean

    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.

  • resizabledefault true
    boolean

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

  • maxFileSizedefault 104857600
    number

    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.

  • maxRowsdefault 1000000
    number

    Rows kept after the header. The rest is left out and the status bar says First 1,000,000 rows.

  • localedefault "en-US"
    string

    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.

  • 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"
    string

    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.

  • highlightColordefault "rgba(250, 204, 21, 0.4)"
    string

    Fill 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)"
    string

    Fill of the current search hit (--csv-viewer-active-highlight).

  • showToolbardefault true
    boolean

    The toolbar with zoom, search, view switches, columns and file actions.

  • showDetailBardefault true
    boolean

    The bar with the address box (go to) and the full value of the active cell.

  • showStatusBardefault true
    boolean

    The bar under the grid: rows and columns, filtered rows, the totals of a selection, and the delimiter and encoding switches.

  • showSearchdefault true
    boolean

    The search button, and Ctrl+F / ⌘F inside the viewer.

  • showViewSwitchesdefault true
    boolean

    The header row, wrap text, row numbers and format switches (toolbar buttons when wide, the ⋯ menu when narrow).

  • showColumnsMenudefault true
    boolean

    The columns menu that shows or hides columns.

  • showDownloaddefault true
    boolean

    The download button (in the ⋯ menu when narrow). It saves the original file, bytes unchanged.

  • showUploaddefault true
    boolean

    Open a file in the ⋯ menu and dropping a file onto the viewer. The file opens locally; onFileUpload hands it to you.

  • heightdefault 640
    number | string

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

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

Dependencies

@tanstack/react-virtuallucide-reactbuttoncheckboxdropdown-menupopovertooltipuse-media-queryui-config

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

Excel ViewerCSV ImportData TableSpreadsheetlibPDF Viewer

Used in

File System

More React media components

DOCX EditorImage compareImage GalleryStep PlayerQR CodeCarousel
All 17 React media components

Articles using this component

  • React Excel Viewer: Show .xlsx Files With Their Real Styles

    Component guides · Oct 16, 2026 · 10 min read

New components by email

New posts, product news and occasional offers from Wingo UI. We count clicks to keep it relevant.

PreviousCarouselNext DOCX Editor
Loading file