npm package: @importkit/react
Description: Drop-in CSV/Excel import widget for React with AI mapping, validation, theming, and templates
Author: Qualitas Imports ehf
Latest version: 0.7.0

# @importkit/react

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

[![npm version](https://img.shields.io/npm/v/@importkit/react.svg)](https://www.npmjs.com/package/@importkit/react)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
npm install @importkit/react
```

## Quick Start

```tsx
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

```tsx
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

```tsx
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"`)

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

## Theming

```tsx
<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](https://demo.importkit.app)

## Documentation

Full documentation: [importkit.app](https://importkit.app)

## License

MIT