How to Use ImportKit: Add CSV/Excel Import to Your React App in 10 Minutes

Source: Dev.to

Overview

Building CSV import functionality from scratch takes weeks—you need file parsing, column‑mapping UI, validation logic, error handling, and Excel support. ImportKit gives you all of this as a drop‑in React component you can integrate in an afternoon.

This guide walks through a common scenario: letting users import contact lists into a CRM application.

Prerequisites

You need:

• A React 18.x or React 19.x application (including Next.js)
• An ImportKit account – sign up at
• About 10 minutes

ImportKit lists React 18 and React 19 as peer dependencies, so it works with any modern React setup.

Step 1: Install the Package

ImportKit is published as @importkit/react on npm. The package is MIT‑licensed and includes TypeScript type definitions.

npm install @importkit/react

The library provides dual ESM/CJS builds via tsup, so it works with both modern and legacy bundlers.

Step 2: Get Your API Key

1. Log into the ImportKit dashboard.
2. Navigate to API Keys → Generate New Key.

The widget requires an API key for authentication and usage tracking. Keys are scoped per user and can be revoked from the dashboard.

• Free tier – 500 rows/month (reset automatically on the 1st via Supabase pg_cron).
• Starter – 5 000 rows/month.
• Pro – 50 000 rows/month.
• Enterprise – unlimited rows.

Step 3: Define Your Data Schema

ImportKit uses a field configuration to describe the data you expect. For a contact import you might define:

const contactFields = [
  {
    name: 'email',
    label: 'Email Address',
    type: 'email',
    required: true,
  },
  {
    name: 'firstName',
    label: 'First Name',
    type: 'text',
    required: true,
  },
  {
    name: 'lastName',
    label: 'Last Name',
    type: 'text',
    required: false,
  },
  {
    name: 'status',
    label: 'Status',
    type: 'enum',
    enum: {
      values: ['Active', 'Inactive', 'Pending'],
      hints: ['enabled,live', 'disabled,off', 'waiting,review'],
    },
  },
  {
    name: 'age',
    label: 'Age',
    type: 'number',
    validate: [
      {
        type: 'min',
        value: 0,
        message: 'Age must be positive',
      },
    ],
  },
];

Field Types

ImportKit supports text, email, number, date, and enum. Each type can have custom validation rules such as:

• Email format checking
• Numeric ranges (min, max)
• String length constraints (minLength, maxLength)
• Regex patterns

The enum type uses a six‑step matching cascade (exact, case‑insensitive, customer‑learned, global‑learned, developer hints, AI semantic) to map messy source values automatically.

Step 4: Add the Widget to Your Component

import { ImportWidget } from '@importkit/react';

function ContactImportPage() {
  const handleComplete = (data: any[]) => {
    console.log('Imported contacts:', data);
    // Send to your API
    fetch('/api/contacts/bulk', {
      method: 'POST',
      body: JSON.stringify(data),
      headers: { 'Content-Type': 'application/json' },
    });
  };

  return (
    <>
      {/* ImportWidget goes here */}
      <ImportWidget
        fields={contactFields}
        apiKey="YOUR_API_KEY"
        onComplete={handleComplete}
      />
    </>
  );
}

The widget handles everything:

• Drag‑and‑drop file upload
• Parsing CSV and Excel files (.csv, .xlsx, .xls)
• Column mapping UI
• Validation & error correction
• Multi‑step guided interface

Step 5: Let AI Handle Column Mapping

When a file is uploaded, ImportKit sends the CSV headers and your target fields to /api/suggest-mapping. This endpoint calls OpenAI gpt‑4o‑mini (temperature = 0) and receives a structured JSON response with confidence scores.

If the AI service is unavailable, the widget falls back to fast substring matching, ensuring imports still work.

Example mapping (CSV columns: “E‑mail”, “First”, “Last”, “Account Status”):

Users can manually override any suggestion.

Step 6: Validate Before Import

ImportKit validates each row in real time, showing inline errors in the preview step. Users can:

• Import only the rows that pass validation, or
• Fix errors directly in the UI before proceeding.

Supported validation rules include:

• Email format
• Numeric ranges (min, max)
• String length (minLength, maxLength)
• Regex patterns
• Enum value matching
• Required‑field enforcement

This pre‑emptive validation reduces bad data entering your system and cuts down on support tickets.

Optional: Use Templates for Reusable Configs

If you have multiple import scenarios (e.g., contacts, products, orders) or want to let power users manage imports themselves, you can save field configurations as templates and load them dynamically:

import { ImportWidget, loadTemplate } from '@importkit/react';

const template = await loadTemplate('contacts');

Templates can be stored in your database or a CDN, making it easy to maintain a library of import definitions across projects.

That’s it!

With just a few minutes of setup, ImportKit gives you robust CSV/Excel import, AI‑assisted column mapping, and comprehensive validation—all wrapped in a polished React component. Happy importing!

ImportKit – Quick Reference Guide

1. Load a Saved Import Configuration

Templates are stored in Supabase’s import_templates table and loaded via the widget’s templateId prop:

This enables consistent imports across users and sessions while reducing implementation time. Non‑technical users can manage import configurations through the dashboard CRUD UI.

2. Optional: Customize the Appearance

ImportKit supports full theming to match your brand. You can customize colors, borders, fonts, and hide the “Powered by ImportKit” branding:

Setting showBranding to false removes the footer for a white‑label experience.

3. Optional: Set Up Webhook Delivery

Note: Webhooks are available on the Pro or Enterprise tier.

1. Configure a webhook URL in the dashboard.
2. ImportKit POSTs the import data to your endpoint after each import completes.

Headers

• X-ImportKit-Signature: HMAC‑SHA256 signature of the request body.
• The secret is generated via crypto.randomBytes(32).

Retry Policy

• Up to 3 attempts with exponential back‑off (1 s → 4 s).
• 10‑second timeout per attempt.

Payload Example

{
  "event": "import.completed",
  "importId": "uuid",
  "rowCount": 150,
  "templateName": "Contact Import",
  "timestamp": "2024-01-28T10:30:00Z"
}

If all retries fail, the failure is logged but does not block the import response. Webhooks are fire‑and‑forget from the user’s perspective.

4. What Happens Behind the Scenes

All authentication is performed via the API key in the request body (no cookies).

5. When to Use ImportKit vs. Building It Yourself

The widget’s source code is MIT‑licensed and available at github.com/gthorr/importkit. The dashboard and backend are part of the hosted service.

6. Further Resources

• GitHub repository:
• Official documentation:

Feel free to open an issue on GitHub for implementation questions or consult the docs for deeper integration details.