Getting Started

Choose Your Approach

ImportCSV offers two ways to integrate:

Option 1: Local Mode (Recommended for Quick Start)

Configuration in your frontend code. No backend required.

npm install @importcsv/react

Option 2: Backend Mode (Recommended for Production)

Configuration stored in database, managed via admin dashboard.

See Backend Setup Guide for full instructions.

Optional: Excel Support

npm install xlsx  # For .xls and .xlsx files

Quick Start

import { CSVImporter } from '@importcsv/react';
import { useState } from 'react';

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Import CSV</button>

      <CSVImporter
        modalIsOpen={isOpen}
        modalOnCloseTriggered={() => setIsOpen(false)}
        onComplete={(data) => {
          console.log(`Imported ${data.num_rows} rows`);
          // data.rows = [{ values: { name: "John", email: "john@example.com" } }]
        }}
        columns={[
          { id: 'name', label: 'Name', validators: [{ type: 'required' }] },
          { id: 'email', label: 'Email', type: 'email' }
        ]}
      />
    </>
  );
}

✅ Automatic file parsing - CSV, TSV, XLS, XLSX ✅ Smart column mapping - AI-powered field matching ✅ Built-in validation - Email, required fields, and more ✅ Large file support - 10,000+ rows with virtual scrolling ✅ Zero configuration - Works out of the box

Default Behavior

By default, ImportCSV enforces strict data validation:

Blocks import if any row has validation errors
Shows clear error messages for each invalid field
Ensures data integrity before import completes

You can customize this behavior:

// Allow import with warnings (include invalid rows)
<CSVImporter
  columns={columns}
  invalidRowHandling="include"
  onComplete={(data) => console.log(data)}
/>

// Filter out invalid rows automatically
<CSVImporter
  columns={columns}
  invalidRowHandling="exclude"
  onComplete={(data) => console.log('Only valid rows:', data)}
/>

Framework Setup

Next.js App Router

'use client';
import { CSVImporter } from '@importcsv/react';

Next.js Pages Router

import dynamic from 'next/dynamic';

const CSVImporter = dynamic(
  () => import('@importcsv/react').then(mod => mod.CSVImporter),
  { ssr: false }
);

Vanilla JavaScript

<script src="https://unpkg.com/@importcsv/react@latest/build/index.js"></script>
<script>
  const importer = CSVImporter.createCSVImporter({
    domElement: document.getElementById('app'),
    columns: [
      { id: 'name', label: 'Name' },
      { id: 'email', label: 'Email' }
    ],
    onComplete: (data) => console.log(data)
  });

  importer.showModal();
</script>

Performance Notes

Large Files (1,000+ rows)

ImportCSV automatically optimizes for large datasets:

Virtual scrolling renders only visible rows
Progressive validation keeps UI responsive
Efficient memory usage with optimized data structures

Bundle Size

The entire library is ~100KB gzipped, including:

Core importer functionality
Virtual scrolling for large datasets
All validation and transformation logic
Auto-injected CSS styles

Production Deployment

Recommended Configuration

<CSVImporter
  columns={columns}
  onComplete={handleComplete}
  primaryColor={brandColor}     // Match your brand
  darkMode={prefersDarkMode}    // Respect user preference
  modalCloseOnOutsideClick={true}  // Better UX
/>

Error Handling

const handleComplete = (data) => {
  try {
    // Process imported data
    processData(data.rows);
    showSuccess(`Imported ${data.num_rows} records`);
  } catch (error) {
    showError('Failed to process imported data');
    console.error(error);
  }
};

Backend Mode (Alternative)

If you need centralized configuration management, webhook notifications, or background processing, consider using backend mode:

// Configuration stored in database
<CSVImporter
  importerKey="your-importer-key"
  apiUrl="https://api.yourapp.com"
  onComplete={(data) => console.log(data)}
/>

See Backend Setup and Backend vs Local Comparison for more details.

What's Next?

API Reference - Complete props documentation
Examples - Production-ready examples
Performance Guide - Handling large datasets
Architecture - Technical deep-dive
Backend Setup - Set up backend-driven mode