Importer SDK

`useExpressCSV(options)`

function useExpressCSV<TSchema>(
  options: UseExpressCSVOptions<TSchema>
): {
  open: (options: OpenOptions<Infer<TSchema>>) => void;
  importerState: ImporterState;
  isInitialising: boolean;
  isOpen: boolean;
};

Options

Option	Description	Type	Required	Default
`schema`	Schema definition created with `x.row()`	`Schema`	Yes	—
`getSessionToken`	Async callback that asks your backend for a short-lived import session token	`() => Promise<string>`	Yes	—
`importIdentifier`	Unique identifier for this import type	`string`	Yes	—
`title`	Title shown in the importer header	`string`	No	—
`preload`	Preload the importer in a hidden iframe for instant display	`boolean`	No	`true`
`debug`	Enable debug logging	`boolean`	No	`false`
`theme`	Theme variable overrides (see Styling)	`ECSVTheme`	No	—
`colorMode`	`'light'`, `'dark'`, or `'system'`	`ColorModePref`	No	—
`customCSS`	Custom CSS injected into the importer	`string`	No	—
`fonts`	Custom font sources	`Record<string, ECSVFontSource>`	No	—
`stepDisplay`	Step indicator style	`'progressBar'`, `'segmented'`, or `'numbered'`	No	`'progressBar'`
`previewSchemaBeforeUpload`	Show expected columns before upload	`boolean`	No	`true`
`columnMatching`	Configure managed column matching or provide a custom matcher	`{ type: "managed"; exact?: boolean; caseInsensitive?: boolean; normalized?: boolean; inference?: boolean } \| { type: "custom"; match: (...) => Promise<...> }`	No	`undefined`
`promptedEdits`	Enable managed prompted edits or provide a custom edit handler	`{ type: "managed" } \| { type: "custom"; edit: (...) => Promise<...> }`	No	`undefined`
`templateDownload`	Offer downloadable template files	`TemplateDownloadOptions<TSchema>`	No	—
`sessionRecovery`	Enable Recovered sessions with either local recovery or a custom adapter implementing `get`, `set`, and `remove`	`SessionRecoveryOptions`	No	—
`locale`	Locale string overrides (see Localization)	`DeepPartial<ExpressCSVLocaleInput>`	No	—
`disableStatusStep`	Skip the success/error status screen	`boolean`	No	—

Return Values

Property	Description	Type
`open`	Opens the importer. Requires `onData` for delivery.	`(options: OpenOptions<T>) => void`
`importerState`	Current importer lifecycle state (reactive)	`ImporterState`
`isInitialising`	`true` while the importer is initializing or opening	`boolean`
`isOpen`	`true` while the importer is open	`boolean`

`open(options)`

Options passed to open().

Option	Description	Type	Required
`onData`	Callback for each chunk. Call `next()` after your backend accepts the current chunk.	`(chunk: RecordsChunk<T>, next: () => void) => void` or `Promise<void>`	Yes
`chunkSize`	Records per chunk (default: 1000)	`number`	No
`onComplete`	Called when all chunks have been processed	`(context: { sessionId: string }) => void`	No
`onCancel`	Called when the user cancels the import	`(context: { sessionId: string }) => void`	No
`onError`	Called when an error occurs	`(error: Error, context: { sessionId: string }) => void`	No
`onImporterOpen`	Called when the importer opens	`() => void`	No
`onImporterClose`	Called when the importer closes	`(reason: 'user_close'	'cancel'
`onStepChange`	Called when the wizard step changes	`(stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void`	No

`RecordsChunk<T>`

interface RecordsChunk<T> {
  records: T[];
  totalChunks: number;
  currentChunkIndex: number;
  totalRecords: number;
  sessionId: string;
  chunkIdempotencyKey: string;
}

Property	Description	Type
`records`	Validated records for this chunk, typed from your schema	`T[]`
`totalChunks`	Total number of chunks in the delivery	`number`
`currentChunkIndex`	0-based index of the current chunk	`number`
`totalRecords`	Total records across all chunks	`number`
`sessionId`	Generated session ID for the current import run	`string`
`chunkIdempotencyKey`	Stable per-chunk idempotency key	`string`

`ImporterState`

The importer moves through these states during its lifecycle:

State	Description
`UNINITIALIZED`	Initial state before the importer iframe is created
`INITIALIZING`	Iframe is loading and establishing a connection
`READY`	Importer is loaded, preloaded, and ready to be opened
`OPENING`	`open()` has been called; creating an import session
`OPEN`	Importer is visible and the user is interacting with it
`CLOSING`	Importer is in the process of closing
`RESETTING`	Importer is resetting for a new import
`ERROR`	An error occurred (check `lastError`)
`DESTROYED`	Importer has been destroyed (component unmounted)

Typical flow: UNINITIALIZED → INITIALIZING → READY → OPENING → OPEN → CLOSING → READY

`ExpressCSVStep`

The wizard step IDs passed to onStepChange:

Step ID	Description
`'upload'`	File upload and optional schema preview
`'select-sheet'`	Sheet selection (multi-sheet files only)
`'select-header'`	Header row selection
`'match-columns'`	Map CSV columns to schema fields
`'match-options'`	Map option values for select/multiselect fields
`'review'`	Review, edit, and validate data before import

Preloading

When preload is true (the default), the importer iframe is created immediately and loads in the background. This means open() displays the importer instantly with no loading screen.

When preload is false, the iframe is only created when open() is called. The user sees a brief loading indicator while the importer initializes.

Use preload: false if the import flow is rarely used and you want to avoid the upfront iframe cost.

Exported Types

All of these are importable from @expresscsv/react:

Type	Description
`Infer<TSchema>`	Extracts the row type from a schema
`UseExpressCSVOptions`	Options for `useExpressCSV()`
`OpenOptions`	Options for `open()`
`RecordsChunk`	Chunk delivered to `onData`
`SessionRecoveryOptions`	Recovered sessions configuration
`LocalSessionRecoveryOptions`	Built-in browser recovery configuration
`CustomSessionRecoveryOptions`	Custom recovery adapter configuration
`SessionRecoveryKey`	Opaque key generated for a recovered session lookup
`RecoveredSession`	Recovered importer session payload wrapper
`RecoveredSessionData`	Recovered row data and column keys
`ColumnMatchingFn`	Custom column matching handler type
`ColumnMatchingParams`	Input passed to a custom column matching handler
`ColumnMatchingResult`	Result returned by a custom column matching handler
`PromptedEditsFn`	Custom prompted edits handler type
`PromptedEditsParams`	Input passed to a custom prompted edits handler
`PromptedEditsResult`	Result returned by a custom prompted edits handler
`ECSVTheme`	Theme variable overrides (single or dual-mode)
`ColorModePref`	`'light'`, `'dark'`, or `'system'`
`ECSVFontSource`	Font source (Google or custom URL)
`TailwindThemeVars`	Theme variable names
`ImporterState`	Importer lifecycle state enum
`ImporterMode`	Importer preload mode enum
`ExpressCSVStep`	Wizard step IDs
`TemplateDownloadConfig`	Template download configuration
`TemplateDownloadFormat`	`'csv'` or `'xlsx'`
`ExpressCSVLocaleInput`	Full locale type
`DeepPartial`	Deep partial utility type
`ImportCancelledError`	Error thrown when import is cancelled
`x`	Schema builder (value, not a type)

On this page