Importer SDK

The React Importer SDK is built around useExpressCSV(). The sections below document its options, return shape, and related types.

`useExpressCSV(options)`

function useExpressCSV<TSchema>(
  options: UseExpressCSVOptions<TSchema>
): {
  open: (options: OpenOptions<Infer<TSchema>>) => void;
  status: ImporterStatus;
};

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	—
`importNamespace`	Stable namespace string your app assigns to this importer configuration. Keep it the same for the same workflow; use a different value for different importers.	`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)	`Theme`	No	—
`colorMode`	`'light'`, `'dark'`, or `'system'`	`ColorModePref`	No	—
`customCSS`	Custom CSS injected into the importer	`string`	No	—
`fonts`	Custom font sources	`Record<string, FontSource>`	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"; columnMatchHandler: (...) => Promise<...> }`	No	`undefined`
`promptedEdits`	Enable managed prompted edits or provide a custom edit handler	`{ type: "managed" } \| { type: "custom"; promptedEditHandler: (...) => 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`
`status`	Current importer lifecycle status (reactive)	`ImporterStatus`

`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`	Delivery packet size. Defaults to `{ unit: "kb", value: 500 }`. `kb` uses decimal kilobytes (`1 KB = 1000 bytes`). Use `{ unit: "kb", value: 500 }` for KB or `{ unit: "rows", value: 500 }` for row counts. Zero or negative values send all records in one chunk.	`ChunkSize`	No
`onComplete`	Called when all chunks have been processed	`(context: { sessionId: string; deliveryId: string }) => void`	No
`onCancel`	Called when the user cancels the import	`(context: { sessionId: string }) => void`	No
`onError`	Called when an error occurs. `deliveryId` is present for delivery failures.	`(error: Error, context: { sessionId: string; deliveryId?: string }) => void`	No
`onOpen`	Called when the importer opens	`(context: { sessionId: string }) => void`	No
`onStepChange`	Called when the importer step changes	`(stepId: ImporterStep, previousStepId?: ImporterStep) => void`	No

`RecordsChunk<T>`

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

Property	Description	Type
`records`	Validated records for this chunk, typed from your schema	`T[]`
`totalChunks`	Total number of chunks in the delivery	`number`
`chunkIndex`	0-based index of the current chunk within this delivery	`number`
`totalRecords`	Total records across all chunks	`number`
`sessionId`	Stable ID for this import run. Use it to group chunks and lifecycle callbacks.	`string`
`deliveryId`	Stable ID for the delivery created when the user finishes the import. Use it with `sessionId` and `chunkIndex` when saving each chunk to your import chunk staging table (a database table or store).	`string`

`ImporterStatus`

The importer moves through these statuses during its lifecycle:

Status	Description
`UNINITIALIZED`	Initial status 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

`ImporterStep`

The importer 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

preload: true (default): the importer iframe loads in the background so open() displays instantly with no loading screen
preload: false: the iframe is created only when open() is called; the user sees a brief loading indicator
Use preload: false when the importer 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()`
`ImportSessionContext`	`{ sessionId: string }` passed to session-scoped lifecycle callbacks
`ImportDeliveryContext`	`{ sessionId: string; deliveryId: string }` passed to delivery-scoped lifecycle callbacks
`ImportErrorContext`	`{ sessionId: string; deliveryId?: string }` passed to `onError`
`RecordsChunk`	Chunk delivered to `onData`
`SessionRecoveryOptions`	Configuration for recovered sessions
`LocalSessionRecoveryOptions`	Built-in browser recovery configuration
`CustomSessionRecoveryOptions`	Custom recovery adapter configuration
`SessionRecoveryKey`	Opaque key generated for a recovered session lookup
`RecoveredSession`	Wrapper type for a recovered-session payload in the importer
`RecoveredSessionData`	Row data and column keys for a recovered session
`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
`Theme`	Theme variable overrides (single or dual-mode)
`ColorModePref`	`'light'`, `'dark'`, or `'system'`
`FontSource`	Font source (Google or custom URL)
`TailwindThemeVars`	Theme variable names
`ImporterStatus`	Importer lifecycle status enum
`ImporterMode`	Importer preload mode enum
`ImporterStep`	Importer 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