SDK Reference

`useExpressCSV(options)`

function useExpressCSV<TSchema>(
  options: UseExpressCSVOptions<TSchema>
): {
  open: (options: OpenOptions<Infer<TSchema>>) => void;
  close: () => void;
  restart: () => void;
  widgetState: WidgetState;
  isOpen: boolean;
  isReady: boolean;
  canRestart: boolean;
  lastError: Error | null;
  connectionStatus: string;
};

Options

Option	Description	Type	Required	Default
`schema`	Schema definition created with `x.row()`	`Schema`	Yes	—
`publishableKey`	Your publishable key from the dashboard	`string`	Yes	—
`importIdentifier`	Unique identifier for this import type	`string`	Yes	—
`title`	Title shown in the widget header	`string`	No	—
`preload`	Preload widget 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 widget	`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`
`templateDownload`	Offer downloadable template files	`TemplateDownloadConfig`	No	—
`saveSession`	Persist session for resuming interrupted imports	`boolean`	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 widget. Requires at least one of `onData` or `webhook`.	`(options: OpenOptions<T>) => void`
`close`	Closes the widget	`() => void`
`restart`	Resets and reopens the widget for a new import	`() => void`
`widgetState`	Current widget state (reactive)	`WidgetState`
`isOpen`	`true` while the widget is open	`boolean`
`isReady`	`true` when the widget is initialized and ready to open	`boolean`
`canRestart`	`true` when the widget can be restarted	`boolean`
`lastError`	Most recent error, or `null`	`Error` or `null`
`connectionStatus`	Iframe connection status	`string`

`open(options)`

Options passed to open(). At least one of onData or webhook must be provided.

Option	Description	Type	Required
`onData`	Callback for each chunk. Call `next()` to receive the next chunk.	`(chunk: RecordsChunk<T>, next: () => void) => void` or `Promise<void>`	*
`webhook`	Webhook endpoint for server-side delivery (see Webhooks)	`WebhookConfig`	*
`chunkSize`	Records per chunk (default: 1000)	`number`	No
`onComplete`	Called when all chunks have been processed	`() => void`	No
`onCancel`	Called when the user cancels the import	`() => void`	No
`onError`	Called when an error occurs	`(error: Error) => void`	No
`onWidgetOpen`	Called when the widget opens	`() => void`	No
`onWidgetClose`	Called when the widget closes	`(reason: string) => void`	No
`onStepChange`	Called when the wizard step changes	`(stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void`	No

* At least one of onData or webhook is required.

`RecordsChunk<T>`

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

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`

`WebhookConfig`

interface WebhookConfig {
  url: string;
  headers?: Record<string, string>;
  method?: "POST" | "PUT" | "PATCH";
  timeout?: number;
  retries?: number;
  metadata?: Record<string, unknown>;
  awaitWebhookArrival?: boolean;
}

See Webhooks for payload structure and server handling.

`WidgetState`

The widget moves through these states during its lifecycle:

State	Description
`UNINITIALIZED`	Initial state before the widget iframe is created
`INITIALIZING`	Iframe is loading and establishing a connection
`READY`	Widget is loaded, preloaded, and ready to be opened
`OPENING`	`open()` has been called; creating an import session
`OPEN`	Widget is visible and the user is interacting with it
`CLOSING`	Widget is in the process of closing
`RESETTING`	Widget is resetting for a new import
`ERROR`	An error occurred (check `lastError`)
`DESTROYED`	Widget 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 widget iframe is created immediately and loads in the background. This means open() displays the widget 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 widget 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`
`WebhookConfig`	Webhook delivery configuration
`DeliveryOptions`	Base delivery options
`ECSVTheme`	Theme variable overrides (single or dual-mode)
`ColorModePref`	`'light'`, `'dark'`, or `'system'`
`ECSVFontSource`	Font source (Google or custom URL)
`TailwindThemeVars`	Theme variable names
`WidgetState`	Widget state enum
`WidgetMode`	Widget 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