API Reference

// Strict mode - blocks import on any error (default)
<CSVImporter
  columns={columns}
  invalidRowHandling="block"
  onComplete={(data) => console.log(data)}
/>

// Filter mode - imports only valid rows
<CSVImporter
  columns={columns}
  invalidRowHandling="exclude"
  onComplete={(data) => {
    // data contains only rows that passed validation
    console.log(`Imported ${data.num_rows} valid rows`);
  }}
/>

// Permissive mode - imports everything with warnings
<CSVImporter
  columns={columns}
  invalidRowHandling="include"
  onComplete={(data) => {
    // data contains all rows, check for errors separately
    console.log(`Imported ${data.num_rows} rows (may include invalid data)`);
  }}
/>

// Example CSV with extra columns:
// Name,Email,Department,Manager,Office
// John,john@example.com,Sales,Jane Smith,Building A

const columns = [
  { id: 'name', label: 'Name' },
  { id: 'email', label: 'Email' },
  { id: 'department', label: 'Department' }
];

// With includeUnmatchedColumns=true
<CSVImporter
  columns={columns}
  includeUnmatchedColumns={true}
  onComplete={(data) => {
    // data.mappedData includes defined columns
    // data.unmappedData includes Manager and Office columns
  }}
/>

interface Column {
  id: string;                      // Unique identifier
  label: string;                   // Display name
  type?: 'string' | 'number' | 'email' | 'date' | 'phone' | 'select';
  validators?: Validator[];        // Validation rules
  transformations?: Transformer[]; // Data transformations
  options?: string[];              // For select type
  description?: string;            // Help text
  placeholder?: string;            // Example value
}

type Validator =
  | { type: 'required'; message?: string }
  | { type: 'unique'; message?: string }
  | { type: 'regex'; pattern: string; message?: string }
  | { type: 'min'; value: number; message?: string }         // For number fields
  | { type: 'max'; value: number; message?: string }         // For number fields
  | { type: 'min_length'; value: number; message?: string }  // For string fields
  | { type: 'max_length'; value: number; message?: string }; // For string fields

validators: [
  { type: 'required' },
  { type: 'unique', message: 'Must be unique' },
  { type: 'regex', pattern: '^[A-Z]+$', message: 'Uppercase only' },
  { type: 'min', value: 0 },
  { type: 'max', value: 100 },
  { type: 'min_length', value: 3 },
  { type: 'max_length', value: 50 }
]

type Transformer =
  | { type: 'trim' }                    // Remove whitespace from start/end
  | { type: 'uppercase' }                // Convert to UPPERCASE
  | { type: 'lowercase' }                // Convert to lowercase
  | { type: 'capitalize' }               // Capitalize First Letter Of Each Word
  | { type: 'remove_special_chars' }     // Keep only alphanumeric and spaces
  | { type: 'normalize_phone' }          // Format as +1234567890
  | { type: 'normalize_date'; format?: string }  // Parse and format dates
  | { type: 'default'; value: string }   // Replace empty with default value
  | { type: 'replace'; find: string; replace: string }  // Find and replace
  | { type: 'custom'; fn: (value: any) => any }  // Custom transformation

// Chain multiple transformations
transformations: [
  { type: 'trim' },                      // First: remove whitespace
  { type: 'lowercase' },                 // Then: convert to lowercase
  { type: 'default', value: 'unknown' }  // Finally: set default if empty
]

// Phone number normalization
transformations: [
  { type: 'normalize_phone' }  // "555-123-4567" → "(555) 123-4567"
]

// Date formatting
transformations: [
  { type: 'normalize_date', format: 'YYYY-MM-DD' }  // "1/15/24" → "2024-01-15"
]

// Custom transformation
transformations: [
  {
    type: 'custom',
    fn: (value) => {
      // Remove currency symbol and parse as number
      return parseFloat(value.replace(/[$,]/g, ''));
    }
  }
]

// Complex example: SKU formatting
transformations: [
  { type: 'trim' },
  { type: 'remove_special_chars' },
  { type: 'replace', find: ' ', replace: '-' },
  { type: 'uppercase' }
]  // "  prod #123  " → "PROD-123"

// Order matters!
column: {
  id: 'email',
  transformations: [
    { type: 'trim' },        // 1st: "  JOHN@EXAMPLE.COM  "
    { type: 'lowercase' }    // 2nd: "john@example.com"
  ]
}

interface ImportData {
  rows: Array<{
    index: number;
    values: Record<string, any>;
  }>;
  columns: Array<{
    id: string;
    label: string;
  }>;
  num_rows: number;
  num_columns: number;
  // When includeUnmatchedColumns is true:
  mappedData?: any[];      // Data for defined columns
  unmappedData?: any[];    // Data for extra columns
}

{
  "num_rows": 2,
  "num_columns": 2,
  "columns": [
    { "id": "name", "label": "Name" },
    { "id": "email", "label": "Email" }
  ],
  "rows": [
    {
      "index": 0,
      "values": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    },
    {
      "index": 1,
      "values": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    }
  ]
}

// No special configuration needed - optimizations are automatic
<CSVImporter
  columns={columns}
  onComplete={handleComplete}
/>

classNames={{
  root: 'my-importer',
  modal: 'my-modal',
  header: 'my-header',
  stepper: 'my-stepper',
  content: 'my-content',
  footer: 'my-footer',
  button: 'my-button',
  input: 'my-input',
  table: 'my-table',
  dropzone: 'my-dropzone'
}}

customStyles={{
  'font-family': 'Inter',
  'font-size': '14px',
  'border-radius': '8px',
  'color-primary': '#3B82F6',
  'color-primary-hover': '#2563EB',
  'color-border': '#E5E7EB',
  'color-text': '#111827',
  'color-background': '#FFFFFF',
  'color-background-modal': '#F9FAFB'
}}

--font-family
--font-size
--base-spacing
--border-radius
--color-primary
--color-primary-hover
--color-secondary
--color-secondary-hover
--color-tertiary
--color-tertiary-hover
--color-border
--color-text
--color-text-soft
--color-text-on-primary
--color-text-on-secondary
--color-background
--color-background-modal
--color-input-background
--color-input-background-soft
--color-background-menu-hover
--color-importer-link
--color-progress-bar

// Just import the component - CSS is included!
import { CSVImporter } from '@importcsv/react';

// No need for: import '@importcsv/react/dist/style.css' ❌

import { CSVImporter } from '@importcsv/react';
import type { Column, Validator, Transformer } from '@importcsv/react';

const columns: Column[] = [
  {
    id: 'email',
    label: 'Email',
    type: 'email',
    validators: [{ type: 'required' }] as Validator[]
  }
];

const importer = CSVImporter.createCSVImporter(config);

importer.showModal();   // Open modal
importer.closeModal();  // Close modal