What is ImportCSV?

ImportCSV is a React component that allows your users to import CSV, XLS, and XLSX files into your application with intelligent column mapping, validation, and error handling.

When to Use ImportCSV

Use ImportCSV when you need to:

• Import customer data - Let users bulk upload contacts, leads, or customer records
• Onboard existing data - Help users migrate from spreadsheets or other tools
• Bulk operations - Enable mass updates, product imports, or inventory management
• Data collection - Accept structured data from clients, partners, or team members

Key Features

• Type-Safe with Zod - Define your schema once, get full TypeScript types automatically
• Intelligent Mapping - AI-powered column matching suggests the right mapping
• High Performance - Handle 10,000+ rows with virtual scrolling and progressive validation
• Production Ready - Built-in validation, transformations, and error handling
• Zero Config - CSS auto-injected, no separate imports needed
• Lightweight - ~100KB gzipped bundle, optimized with Preact

Installation

npm install @importcsv/react zod

Optional: Excel Support

npm install xlsx  # For .xls and .xlsx files

Quick Start

Here's a complete example to get you started:

'use client'; // Remove if not using Next.js App Router

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

// Define your data schema
const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  company: z.string().optional()
});

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

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

      <CSVImporter
        modalIsOpen={isOpen}
        modalOnCloseTriggered={() => setIsOpen(false)}
        schema={schema}
        onComplete={(data) => {
          // data is typed: { name: string; email: string; company?: string }[]
          console.log(`Imported ${data.length} customers`);

          // Send to your API
          fetch('/api/customers/import', {
            method: 'POST',
            body: JSON.stringify(data)
          });
        }}
      />
    </>
  );
}

What You Get

✅ 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 ✅ Full TypeScript types - Automatic type inference from schema ✅ Zero configuration - Works out of the box

Framework-Specific Guides

How It Works

1. User uploads file - CSV, XLS, or XLSX
2. Column mapping - AI suggests mappings, user can adjust
3. Validation - Data validated against your Zod schema
4. Error handling - Clear error messages, option to fix or skip invalid rows
5. Import complete - Type-safe data returned to your app

Next Steps

• Next.js Guide - Complete Next.js integration
• React Guide - React and Vite setup
• Configuration - Customize the importer
• API Reference - Complete props documentation