React component reference

Package: @bootstrapware/importer
Styles: @bootstrapware/importer/styles.css

Props

Prop	Type	Required	Notes
onComplete	(rows, meta) => void \| Promise<void>	yes	Valid rows only, plus ImportMeta. Throw or reject to show an error and retry.
fields	ImporterField[]	for local mode	Schema in code. Supports valueMap, transform, and validate on fields.
importerId	string	hosted	With publishableKey
publishableKey	string	hosted	Browser-safe
apiBaseUrl	string	no	Defaults to https://importer.bootstrapware.co
duplicateKey	string	no	Field key for in-file duplicates
dateOrder	"MDY" \| "DMY"	no	Slash/dash/dot numeric dates. Default MDY. Day or month above 12 is unambiguous. ISO stays YYYY-MM-DD.
numberLocale	"us" \| "eu" \| "auto"	no	Default auto. Semicolon CSVs prefer EU (bare 1.234 → 1234).
dir	"ltr" \| "rtl"	no	Widget text direction. Default ltr. Use with strings for RTL chrome copy.
strings	Partial<ImporterStrings>	no	Override chrome copy. Missing keys stay English. Type-error messages are not in this map. Not an ARIA grid; no WCAG AA claim.
title	string	no	Default "Import spreadsheet"
theme	"light" \| "dark"	no	Omit for the light cream default. No `data-theme` and no system theme.
presentation	"section" \| "modal" \| "window" \| "launcher"	no	Default `section` (inline). Modal, window, and launcher start closed unless `defaultOpen`. A successful import closes those overlays. Escape closes them. The backdrop closes modal and launcher.
useWorker	boolean	no	Opt-in Web Worker parse with main-thread fallback. Not a million-row editor.
primaryKey	string	no	With `existingKeys`, fills `meta.upsert`.
existingKeys	(string \| number)[]	no	Host-owned prior keys. Never sent to Bootstrapware.
defaultOpen	boolean	no	Open modal, window, or launcher on first render. Ignored for `section`.
onCancel	() => void	no	Cancel on preview

Hosted mode is used when both importerId and publishableKey are set. Local fields can be omitted until hosted config loads.

Theme

theme is "light" | "dark". Omit it and the shell stays the light cream default: the root has no data-theme attribute. theme="light" sets data-theme="light" and keeps those light tokens. theme="dark" sets data-theme="dark" and applies the dark shell. v1 does not follow prefers-color-scheme or the system theme.

Hosts may set these CSS custom properties on the embed root (.bsw-importer). These overrides are the supported API. Do not fight .bsw-* classes. When theme="dark" is set, target .bsw-importer[data-theme="dark"] so your values win over the dark defaults.

--bsw-bg
--bsw-panel
--bsw-fg
--bsw-muted
--bsw-line
--bsw-accent
--bsw-accent-fg
--bsw-radius

.bsw-importer[data-theme="dark"] {
  --bsw-bg: #161714;
  --bsw-panel: #22241c;
  --bsw-fg: #f4f4ee;
  --bsw-muted: #b3b4aa;
  --bsw-line: #4a4c42;
  --bsw-accent: #c8ef00;
  --bsw-accent-fg: #161714;
  --bsw-radius: 12px;
}

Hosted primaryColor, when set, writes --bsw-accent inline on the root and overrides the theme accent.

Flow

Upload → map columns (pick a sheet when the workbook has more than one, and pick the header row when title rows sit above the real headers) → preview (first 100 rows shown; uncheck Include to leave a valid row out) → import the included valid rows, download errors, or download valid rows. Preview stays blocked until every required field is mapped. Assigning a header to one field clears it from other fields. Column dropdowns show sample cell values from the file.

On the upload step, once local fields or hosted published config is known, Download template.csv generates a file in the browser. Headers use field labels, falling back to keys when a label is empty. One example row is derived from field type. The template is not fetched from Bootstrapware. Paste from clipboard and Ctrl/Cmd+V parse text/plain (including tab-separated Excel/Sheets copies) in the browser.

Related: Fields · Column mapping · Validation · onComplete · Quickstart