API Reference

Complete reference for all Spreadsheet Validator exports.

TableReader

The main component. Reads a file, validates it against a Zod schema, and renders an interactive table with error highlighting.

import TableReader from "spreadsheet-validator"

Props

Prop	Type	Default	Description
`file`	`File \| null`	required	The file to parse and validate
`schema`	`ZodObject<T>`	—	Zod schema for column validation
`errorIssuesLog`	`(errors: ErrorLog[] \| undefined) => void`	—	Callback with all validation errors
`onTableData`	`(data: T[]) => void`	—	Callback with valid rows only
`columnInfo`	`{ name: keyof T; message: string }[]`	—	Info tooltips for column headers
`styleTable`	`StyleTable`	—	Custom table styling
`rowHeight`	`number`	`36`	Row height in pixels for virtual scrolling
`overscan`	`number`	`5`	Extra rows rendered outside viewport
`containerHeight`	`number`	`600`	Height of the scrollable container
`loadingComponent`	`React.ReactNode`	—	Custom loading UI while parsing

Example

<TableReader
  file={file}
  schema={schema}
  onTableData={(data) => setValidData(data)}
  errorIssuesLog={(errors) => setErrors(errors)}
  columnInfo={[{ name: "email", message: "Valid email required" }]}
  styleTable={{ headerColor: "#1a1a2e" }}
  containerHeight={500}
  loadingComponent={<Spinner />}
/>

ErrorLog

Extends Zod's $ZodIssue with spreadsheet-specific fields.

type ErrorLog = z.core.$ZodIssue & {
  column?: string
  rowIndex?: number
}

Fields

Field	Type	Description
`message`	`string`	Human-readable error message
`code`	`string`	Zod error code
`path`	`(string \| number)[]`	Path to the invalid field
`column`	`string`	Column name where the error occurred
`rowIndex`	`number`	Row index in the spreadsheet

StyleTable

Configuration object for table appearance.

interface StyleTable {
  backgroundColor?: string
  borderColor?: string
  headerColor?: string
  textColor?: string
  tableBorderColor?: string
  tableBorderRadius?: string
  fontFamilyTable?: string
  fontFamilyHeader?: string
  paddingCell?: string
  paddingHeader?: string
}

ColumnInfo

Configuration for column header tooltips.

interface ColumnInfo {
  name: string
  message: string
}

SpreadSheetData

Internal data type for parsed spreadsheet rows.

interface SpreadSheetData {
  [key: string]: string | number
  __rowNum__: number
}

The __rowNum__ property tracks the original row position in the file and is used internally for error mapping.

PreviousCustom Styling