ExcelImport
ExcelImport is a modal wizard from the @svar-ui/react-excel-import package. It uploads .xlsx, .csv, or .tsv files, lets users map spreadsheet columns to card fields, and returns transformed rows. Mount it conditionally and unmount it in the onClose handler.
Usage
import { ExcelImport } from "@svar-ui/react-excel-import";
<ExcelImport
fields={FieldDefinition[]}
generateIds={boolean}
onImport={(rows, result) => void}
onClose={() => void}
/>
The component takes configuration as individual props (spread an object if needed - <ExcelImport {...config} />). A single config prop doesn't work. The component reads props once at mount; remount it to apply a new config.
Props:
| Prop | Type | Default | Description |
|---|---|---|---|
fields | FieldDefinition[] | - | Target output fields. Required. |
generateIds | boolean | false | Assigns numeric IDs to rows that lack them |
headerRow | boolean | true | Treats the first row as headers |
autoDetection | boolean | true | Auto-match columns to fields by name and type. Mappings are kept per sheet; switching to a sheet without mappings runs auto-detection for it |
autoClose | boolean | false | Closes after import instead of showing a summary |
selectors | "both" | "top" | "right" | "both" | Column mapping UI layout |
accept | string | ".xlsx,.csv,.tsv" | Accepted file types |
previewRowCount | number | 10 | Number of preview rows shown (all rows are imported) |
data | ParsedExcelData | undefined | Pre-parsed data; skips the upload stage |
onImport | (rows: TransformedRow[], result: ImportResult) => void | - | Fires after transform with the mapped rows |
validate | (mappings: FieldMappings, sheet: ParsedSheetData) => ValidationResult | - | Validates mappings before import; return valid: false to disable the Import button |
onClose | () => void | - | Fires on close; the host must unmount the component |
FieldDefinition:
| Field | Type | Description |
|---|---|---|
id | string | Output key in the transformed row |
label | string | Display label shown in the mapping UI |
expectedType | "text" | "number" | "date" | "boolean" | "mixed" | Converts values strictly to this type; skips incompatible rows |
dateUTC | boolean | Returns dates whose UTC fields hold the spreadsheet wall-clock value; dates are local by default |
dateFormat | string | Display format for date values in the preview. Default: "Y-m-d" |
required | boolean | Skips rows where this field is empty |
keywords | string[] | Extra terms for auto-detection matching |
Styling:
The dialog has a fixed size of min(95vw, 1100px) × min(90vh, 624px) and goes full-screen at viewport widths of 768px and below. Override the size with a CSS rule:
dialog.wx-modal .wx-modal-content {
width: min(95vw, 900px);
height: min(90vh, 560px);
}
Example
Importing spreadsheet rows into the kanban board:
import { useState, useRef } from "react";
import { Kanban } from "@svar-ui/react-kanban";
import { ExcelImport } from "@svar-ui/react-excel-import";
function App() {
const api = useRef(null);
const [open, setOpen] = useState(false);
const handleImport = cards => {
cards.forEach(card => (card.column = card.column || "todo"));
api.current.exec("provide-data", { cards });
setOpen(false);
};
return (
<>
<button onClick={() => setOpen(true)}>Import from Excel</button>
<Kanban ref={api} cards={cards} columns={columns} />
{open && (
<ExcelImport
fields={[
{ label: "Title", id: "label" },
{ label: "Deadline", id: "deadline" },
{ label: "Description", id: "description" },
]}
generateIds={true}
onImport={handleImport}
onClose={() => setOpen(false)}
/>
)}
</>
);
}
Related
- Export and import guide - import workflow and provide-data usage
- provide-data - upserts imported cards into the store