API 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 | Type | Required | Default | Description |
|---|---|---|---|---|
schema | Schema | Yes | — | Schema definition created with x.row() |
publishableKey | string | Yes | — | Your publishable key from the dashboard |
importIdentifier | string | Yes | — | Unique identifier for this import type |
title | string | No | — | Title shown in the widget header |
preload | boolean | No | true | Preload widget in a hidden iframe for instant display |
debug | boolean | No | false | Enable debug logging |
theme | ECSVTheme | No | — | Theme variable overrides (see Styling) |
colorMode | ColorModePref | No | — | 'light', 'dark', or 'system' |
customCSS | string | No | — | Custom CSS injected into the widget |
fonts | Record<string, ECSVFontSource> | No | — | Custom font sources |
stepDisplay | 'progressBar', 'segmented', or 'numbered' | No | 'progressBar' | Step indicator style |
previewSchemaBeforeUpload | boolean | No | true | Show expected columns before upload |
templateDownload | TemplateDownloadConfig | No | — | Offer downloadable template files |
saveSession | boolean | No | — | Persist session for resuming interrupted imports |
locale | DeepPartial<ExpressCSVLocaleInput> | No | — | Locale string overrides (see Localization) |
disableStatusStep | boolean | No | — | Skip the success/error status screen |
Return Values
| Property | Type | Description |
|---|---|---|
open | (options: OpenOptions<T>) => void | Opens the widget. Requires at least one of onData or webhook. |
close | () => void | Closes the widget |
restart | () => void | Resets and reopens the widget for a new import |
widgetState | WidgetState | Current widget state (reactive) |
isOpen | boolean | true while the widget is open |
isReady | boolean | true when the widget is initialized and ready to open |
canRestart | boolean | true when the widget can be restarted |
lastError | Error or null | Most recent error, or null |
connectionStatus | string | Iframe connection status |
open(options)
Options passed to open(). At least one of onData or webhook must be provided.
| Option | Type | Required | Description |
|---|---|---|---|
onData | (chunk: RecordsChunk<T>, next: () => void) => void or Promise<void> | * | Callback for each chunk. Call next() to receive the next chunk. |
webhook | WebhookConfig | * | Webhook endpoint for server-side delivery (see Webhooks) |
chunkSize | number | No | Records per chunk (default: 1000) |
onComplete | () => void | No | Called when all chunks have been processed |
onCancel | () => void | No | Called when the user cancels the import |
onError | (error: Error) => void | No | Called when an error occurs |
onWidgetOpen | () => void | No | Called when the widget opens |
onWidgetClose | (reason: string) => void | No | Called when the widget closes |
onStepChange | (stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void | No | Called when the wizard step changes |
* At least one of onData or webhook is required.
RecordsChunk<T>
interface RecordsChunk<T> {
records: T[];
totalChunks: number;
currentChunkIndex: number;
totalRecords: number;
}| Property | Type | Description |
|---|---|---|
records | T[] | Validated records for this chunk, typed from your schema |
totalChunks | number | Total number of chunks in the delivery |
currentChunkIndex | number | 0-based index of the current chunk |
totalRecords | number | Total records across all chunks |
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) |