ImportCSV

A production-ready React component for importing CSV, XLS, and XLSX files with intelligent column mapping, validation, and support for large datasets.

Why ImportCSV?

⚡ High Performance

Handle 10,000+ rows with virtual scrolling and progressive validation

📦 Lightweight

~100KB gzipped bundle, optimized with Preact

🎨 Zero Config

CSS auto-injected, no separate imports needed

🛠️ Production Ready

Built-in validation, transformations, and error handling

Quick Start

npm install @importcsv/react

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

<CSVImporter
  columns={[
    { id: 'name', label: 'Name', validators: [{ type: 'required' }] },
    { id: 'email', label: 'Email', type: 'email' }
  ]}
  onComplete={data => console.log(data)}
/>

Key Features

🚀 Performance at Scale

Virtual Scrolling: Efficiently render 10,000+ rows without browser freezing
Progressive Validation: Validates first 50 rows instantly, processes rest asynchronously
Optimized Bundle: ~100KB gzipped using Preact internals

📊 Data Processing

File Support: CSV, XLS, XLSX, TSV formats
Smart Mapping: Automatic column detection and mapping
10+ Transformations: trim, uppercase, normalize phone/date, custom functions
Comprehensive Validation: Required, unique, regex, min/max, custom validators

🤖 AI-Powered Features

Smart Column Mapping: AI suggests the best column mappings
Natural Language Transformations: Fix errors and transform data with simple prompts
Validation Auto-Fix: Automatically correct common validation errors

🎨 Developer Experience

TypeScript Support: Fully typed API
Auto-injected CSS: No separate stylesheet imports
Framework Agnostic: Works with React, Next.js, vanilla JavaScript
Dark Mode: Built-in theme support

Performance Metrics

Metric	Value
Bundle Size	~100KB gzipped
Max Rows Tested	10,000+
Initial Validation	50 rows (instant)
Progressive Validation	Remaining rows (async)
Dependencies	Minimal (Preact-based)

Choose Your Setup

🚀 Local Mode (Quick Start)

Self-contained React component with configuration in code. Perfect for prototypes and simple use cases.

<CSVImporter
  columns={[...]}
  onComplete={data => console.log(data)}
/>

⚡ Backend Mode (Production)

Database-driven configuration with admin dashboard. Ideal for production apps with dynamic requirements.

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

Compare Local vs Backend →

Quick Links

🚀 Getting Started

5-minute setup guide

🎮 Playground

Interactive configuration tool

📖 API Reference

Complete props and methods

💡 Examples

Production-ready examples

Backend Features

🔧 Backend Setup

Set up FastAPI backend and database

📊 Admin Dashboard

Manage importers through web UI

🔌 API Reference

REST API documentation

⚖️ Choose Your Mode

Local vs Backend comparison