Skip to main content

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:

PropTypeDefaultDescription
fieldsFieldDefinition[]-Target output fields. Required.
generateIdsbooleanfalseAssigns numeric IDs to rows that lack them
headerRowbooleantrueTreats the first row as headers
autoDetectionbooleantrueAuto-match columns to fields by name and type. Mappings are kept per sheet; switching to a sheet without mappings runs auto-detection for it
autoClosebooleanfalseCloses after import instead of showing a summary
selectors"both" | "top" | "right""both"Column mapping UI layout
acceptstring".xlsx,.csv,.tsv"Accepted file types
previewRowCountnumber10Number of preview rows shown (all rows are imported)
dataParsedExcelDataundefinedPre-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:

FieldTypeDescription
idstringOutput key in the transformed row
labelstringDisplay label shown in the mapping UI
expectedType"text" | "number" | "date" | "boolean" | "mixed"Converts values strictly to this type; skips incompatible rows
dateUTCbooleanReturns dates whose UTC fields hold the spreadsheet wall-clock value; dates are local by default
dateFormatstringDisplay format for date values in the preview. Default: "Y-m-d"
requiredbooleanSkips rows where this field is empty
keywordsstring[]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)}
/>
)}
</>
);
}