Import Wizard

The Import Wizard is a multi-step component designed to simplify the process of importing data from CSV or Excel files. It handles file parsing, column mapping, validation, and data preview before finalizing the import.

Usage

import { ImportWizard } from '@orbitusdev/components/importer';
import type { ImportDefinition } from '@orbitusdev/importer';
 
const userImportDefinition: ImportDefinition = {
  key: 'user-import',
  label: 'Users',
  fields: [
    { key: 'email', label: 'Email', required: true },
    { key: 'name', label: 'Full Name' },
    { key: 'role', label: 'Role', type: 'select', options: ['admin', 'user'] }
  ]
};
 
export default function ImportPage() {
  const handleFinish = async (rows, options) => {
    // Call API to save data
    return await saveUsers(rows, options);
  };
 
  return <ImportWizard definition={userImportDefinition} onFinish={handleFinish} />;
}

Workflow Steps

1. Upload: User selects a CSV or Excel (.xlsx) file. Validates file size and format.
2. Sheet Selection: If the Excel file has multiple sheets, the user selects which one to process.
3. Map: The wizard attempts to auto-map file columns to the definition fields. Users can manually adjust these mappings.
4. Preview: Displays the parsed data. Users can:
   • Edit cell values directly.
   • See validation errors (highlighted in red).
   • Choose a “Duplicate Strategy” (Skip, Update, Error).
   • Run a “Dry Run” simulation.
5. Result: Shows the outcome of the import (Success/Failure counts) and allows downloading a log of failed rows if any errors occurred.

Components

ImportWizard

The main container that orchestrates the steps and state (current step, parsed data, mapping, etc.).

FileUploader

Handles file drag-and-drop and selection. Supports file type restriction and size limits.

ColumnMapper

Interface for mapping columns from the uploaded file to the required system fields defined in ImportDefinition. Shows mapping status and validates required fields.

DataEditor

A spreadsheet-like view for inspecting and correcting data before import. Uses @tanstack/react-table for rendering and supports in-cell editing.

DuplicateStrategySelector

Allows the user to define how to handle duplicate records (e.g., based on unique keys like Email). Options: SKIP, UPDATE, ERROR. (Note: The backend implementation must support these strategies).

Configuration (ImportDefinition)

The behavior of the wizard is driven by the ImportDefinition object: