@importkit/react

Drop-in CSV/Excel import widget for React with AI-powered field mapping, validation, and enum value matching.

Features

• Drag & drop CSV and Excel file uploads
• AI-powered mapping automatically matches CSV columns to your fields
• Enum value mapping with intelligent matching (exact, case-insensitive, learned, AI semantic)
• Real-time validation with inline editing to fix errors
• Theming to match your brand
• Templates for consistent imports across users

Installation

npm install @importkit/react

Quick Start

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

function App() {
  return (
    <ImportWidget
      apiKey="your-api-key"
      fields={[
        { name: 'email', label: 'Email', type: 'email', required: true },
        { name: 'name', label: 'Full Name', required: true },
        { name: 'role', label: 'Role', type: 'enum', enum: { values: ['Admin', 'User', 'Guest'] } },
      ]}
      onComplete={(data) => {
        console.log('Imported rows:', data);
      }}
    />
  );
}

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | Yes | Your ImportKit API key | | fields | Field[] | Yes* | Field definitions for mapping | | templateId | string | No | Use a saved template instead of inline fields | | onComplete | (data: ImportedRow[]) => void | Yes | Callback with validated data | | onError | (error: Error) => void | No | Error callback | | theme | ImportWidgetTheme | No | Custom styling | | showBranding | boolean | No | Show "Powered by ImportKit" (default: true) | | apiBaseUrl | string | No | Custom API URL (default: https://dashboard.importkit.app) |

*Required if templateId is not provided

Field Definition

interface Field {
  name: string;           // Internal field name
  label: string;          // Display label
  required?: boolean;     // Is this field required?
  type?: 'text' | 'email' | 'number' | 'date' | 'enum';
  enum?: EnumDefinition;  // For enum fields
  validate?: ValidationRule[];
}

interface EnumDefinition {
  values: string[];       // Allowed values
  hints?: string[];       // Alternative names for each value (same order as values)
  allowEmpty?: boolean;   // Allow empty values
  defaultValue?: string;  // Default if empty
}

Validation Rules

const fields = [
  {
    name: 'age',
    label: 'Age',
    type: 'number',
    validate: [
      { type: 'min', value: 0, message: 'Age must be positive' },
      { type: 'max', value: 150, message: 'Invalid age' },
    ],
  },
  {
    name: 'status',
    label: 'Status',
    validate: [
      { type: 'oneOf', value: ['active', 'inactive'], message: 'Must be active or inactive' },
    ],
  },
];

Available rules: email, number, regex, min, max, minLength, maxLength, oneOf

Enum Value Mapping

For enum fields, ImportKit uses a 6-step cascade to match source values:

1. Exact match - "Admin" → "Admin"
2. Case-insensitive - "admin" → "Admin"
3. Customer learned - Previously corrected mappings for your account
4. Global learned - Commonly used mappings across all users
5. Hint matching - Matches against your provided hints
6. AI semantic - Uses AI to match based on meaning ("Administrator" → "Admin")

{
  name: 'status',
  label: 'Status',
  type: 'enum',
  enum: {
    values: ['Active', 'Inactive', 'Pending'],
    hints: ['enabled,live', 'disabled,off', 'waiting,review'],
  }
}

Theming

<ImportWidget
  apiKey="..."
  fields={fields}
  onComplete={handleComplete}
  theme={{
    primaryColor: '#6366f1',    // Indigo
    successColor: '#22c55e',    // Green
    errorColor: '#ef4444',      // Red
    borderColor: '#e5e7eb',
    borderRadius: '12px',
    fontFamily: 'Inter, sans-serif',
    fontSize: '14px',
  }}
/>

Demo

Try the live demo: demo.importkit.app

Documentation

Full documentation: importkit.app

License

MIT