ImportCSV

https://docs.importcsv.com/
Admin
ImportCSV is an embeddable React component for importing CSV, XLS, and XLSX files with intelligent...
Tokens:52,123
Snippets:515
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install backend dependencies

Source: https://docs.importcsv.com/self-hosting/getting-started

Creates a virtual environment and installs Python dependencies for the backend.

```bash
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```

--------------------------------

### Install ImportCSV and Zod

Source: https://docs.importcsv.com/getting-started

Install the core package and the Zod validation library.

```bash
npm install @importcsv/react zod
```

--------------------------------

### Start admin dashboard

Source: https://docs.importcsv.com/self-hosting/getting-started

Starts the admin dashboard development server. The dashboard will be available at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### Install Excel Support

Source: https://docs.importcsv.com/getting-started

Optional installation required to enable support for .xls and .xlsx file formats.

```bash
npm install xlsx  # For .xls and .xlsx files
```

--------------------------------

### Install ImportCSV and dependencies

Source: https://docs.importcsv.com/getting-started/react

Install the required packages. The second command is optional and adds Excel support.

```bash
npm install @importcsv/react zod
# Optional: for Excel support
npm install xlsx
```

--------------------------------

### Install xlsx library for Excel support

Source: https://docs.importcsv.com/getting-started/react

Install the xlsx library to enable Excel file support in ImportCSV.

```bash
npm install xlsx
```

--------------------------------

### Start backend services

Source: https://docs.importcsv.com/self-hosting/getting-started

Starts the API server and the worker for background processing. The API will be available at http://localhost:8000.

```bash
# Terminal 1: Start API server
uvicorn app.main:app --reload

# Terminal 2: Start worker for background processing
python -m app.worker
```

--------------------------------

### Install admin dashboard dependencies

Source: https://docs.importcsv.com/self-hosting/getting-started

Installs npm dependencies for the admin dashboard.

```bash
cd admin
npm install
```

--------------------------------

### List Importers Response

Source: https://docs.importcsv.com/self-hosting/api-reference

Example of a successful response from the GET /importers endpoint. Returns an array of importer objects with the specified fields.

```json
[
  {
    "id": "uuid",
    "name": "Customer Import",
    "key": "uuid-key-string",
    "description": "Import customer data",
    "fields": [...],
    "webhook_url": "https://example.com/webhook",
    "webhook_enabled": true,
    "include_data_in_webhook": false,
    "webhook_data_sample_size": 10,
    "include_unmatched_columns": false,
    "filter_invalid_rows": false,
    "disable_on_invalid_rows": false,
    "dark_mode": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```

--------------------------------

### Validation configuration example

Source: https://docs.importcsv.com/self-hosting/admin-dashboard

Example JSON configuration for a validation rule. Shows a required field with a custom error message.

```json
{
  "type": "required",
  "message": "Customer ID is required"
}
```

--------------------------------

### Transformer usage examples

Source: https://docs.importcsv.com/reference/api

Shows multiple transformation chains: chaining trim, lowercase, and default; phone normalization; date formatting; a custom function that removes currency symbols; and a complex SKU formatting example.

```javascript
// Chain multiple transformations
transformations: [
  { type: 'trim' },                      // First: remove whitespace
  { type: 'lowercase' },                 // Then: convert to lowercase
  { type: 'default', value: 'unknown' }  // Finally: set default if empty
]

// Phone number normalization
transformations: [
  { type: 'normalize_phone' }  // "555-123-4567" → "(555) 123-4567"
]

// Date formatting
transformations: [
  { type: 'normalize_date', format: 'YYYY-MM-DD' }  // "1/15/24" → "2024-01-15"
]

// Custom transformation
transformations: [
  {
    type: 'custom',
    fn: (value) => {
      // Remove currency symbol and parse as number
      return parseFloat(value.replace(/[$,]/g, ''));
    }
  }
]

// Complex example: SKU formatting
transformations: [
  { type: 'trim' },
  { type: 'remove_special_chars' },
  { type: 'replace', find: ' ', replace: '-' },
  { type: 'uppercase' }
]  // "  prod #123  " → "PROD-123"
```

--------------------------------

### Get Importer Response

Source: https://docs.importcsv.com/self-hosting/api-reference

Example response from the GET /importers/{importer_id} endpoint. Includes field definitions with id and label computed from name and display_name respectively.

```json
{
  "id": "uuid",
  "name": "Customer Import",
  "key": "uuid-key-string",
  "description": "Import customer data",
  "fields": [
    {
      "name": "email",
      "display_name": "Email Address",
      "id": "email",              // Computed from name
      "label": "Email Address",    // Computed from display_name
      "type": "email",
      "validators": [
        {
          "type": "required",
          "message": "Email is required"
        }
      ],
      "transformations": [
        { "type": "trim" },
        { "type": "lowercase" }
      ],
      "options": null
    }
  ],
  "webhook_url": "https://example.com/webhook",
  "webhook_enabled": true,
  "include_data_in_webhook": false,
  "webhook_data_sample_size": 10,
  "include_unmatched_columns": false,
  "filter_invalid_rows": false,
  "disable_on_invalid_rows": false,
  "dark_mode": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

--------------------------------

### Create Import Mapping Example

Source: https://docs.importcsv.com/self-hosting/api-reference

Example of the 'mapping' JSON object provided in the POST /imports request body, mapping CSV column names to importer field names.

```json
{
  "CSV Column Name": "email",
  "Customer Name": "name"
}
```

--------------------------------

### Get Import Status Response

Source: https://docs.importcsv.com/self-hosting/api-reference

Example response from the GET /imports/{import_id} endpoint. Possible statuses: pending, processing, completed, or failed.

```json
{
  "id": "uuid",
  "importer_id": "uuid",
  "status": "completed",
  "num_rows": 100,
  "num_errors": 2,
  "errors": [
    {
      "row": 5,
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:01:00Z"
}
```

--------------------------------

### POST /imports

Source: https://docs.importcsv.com/self-hosting/api-reference

Starts a new import job. The request is multipart/form-data with a file, importer_id, and mapping.

```APIDOC
## POST /imports

### Description
Start a new import job.

### Method
POST

### Endpoint
/imports

### Parameters
#### Request Body (multipart/form-data)
- **file** (file) - Required - CSV/Excel file
- **importer_id** (string) - Required - UUID of the importer
- **mapping** (object) - Required - JSON object mapping CSV columns to importer fields

### Request Example
```json
{
  "CSV Column Name": "email",
  "Customer Name": "name"
}
```

### Response
#### Success Response (200)
- **id** (string) - Import job ID
- **importer_id** (string) - Importer ID
- **status** (string) - Status of the import job
- **created_at** (string) - Creation timestamp

#### Response Example
```json
{
  "id": "uuid",
  "importer_id": "uuid",
  "status": "processing",
  "created_at": "2024-01-01T00:00:00Z"
}
```
```

--------------------------------

### Validator usage examples

Source: https://docs.importcsv.com/reference/api

Shows a validators array with examples of each validator type, including custom messages and patterns.

```javascript
validators: [
  { type: 'required' },
  { type: 'unique', message: 'Must be unique' },
  { type: 'regex', pattern: '^[A-Z]+$', message: 'Uppercase only' },
  { type: 'min', value: 0 },
  { type: 'max', value: 100 },
  { type: 'min_length', value: 3 },
  { type: 'max_length', value: 50 }
]
```

--------------------------------

### Transformation order example

Source: https://docs.importcsv.com/reference/api

Shows that transformations are applied in the order they are defined, using a column with trim then lowercase to convert an email to lowercase.

```javascript
// Order matters!
column: {
  id: 'email',
  transformations: [
    { type: 'trim' },        // 1st: "  JOHN@EXAMPLE.COM  "
    { type: 'lowercase' }    // 2nd: "john@example.com"
  ]
}
```

--------------------------------

### Create Import POST /imports

Source: https://docs.importcsv.com/self-hosting/api-reference

Start a new import job with multipart/form-data: 'file' (CSV/Excel), 'importer_id' (UUID), and 'mapping' (JSON object mapping CSV columns to importer fields).

```http
POST /imports
```

--------------------------------

### Quick Start (Vite) - src/App.tsx

Source: https://docs.importcsv.com/getting-started/react

A complete React component that uses the CSVImporter with a Zod schema to import user data and display the results.

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

// Define your data schema
const userSchema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.string().email('Invalid email address'),
  age: z.number().min(18, 'Must be 18 or older').optional(),
  role: z.enum(['admin', 'user', 'guest'])
});

type User = z.infer<typeof userSchema>;

function App() {
  const [isOpen, setIsOpen] = useState(false);
  const [users, setUsers] = useState<User[]>([]);

  return (
    <div className="App">
      <button onClick={() => setIsOpen(true)}>
        Import Users
      </button>

      <CSVImporter
        modalIsOpen={isOpen}
        modalOnCloseTriggered={() => setIsOpen(false)}
        schema={userSchema}
        onComplete={(data: User[]) => {
          setUsers(data);
          setIsOpen(false);
        }}
      />

      {/* Display imported users */}
      {users.length > 0 && (
        <div>
          <h2>Imported Users ({users.length})</h2>
          <ul>
            {users.map((user, i) => (
              <li key={i}>{user.name} - {user.email}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

export default App;
```

--------------------------------

### Sample CSV data for employee import

Source: https://docs.importcsv.com/configuration/validation

Sample CSV data with employee records matching the schema fields: Employee ID, Email, Age, Department, Salary, and Start Date.

```csv
Employee ID,Email,Age,Department,Salary,Start Date
EMP001,john@example.com,28,Engineering,75000,2024-01-15T00:00:00Z
EMP002,jane@example.com,32,Sales,65000,2024-02-01T00:00:00Z
```

--------------------------------

### Backend Mode CSVImporter Configuration

Source: https://docs.importcsv.com/self-hosting/comparison

Example of using the CSVImporter component with an importerKey and apiUrl for database-managed configurations.

```javascript
// Configuration stored in database, managed via admin
<CSVImporter
  importerKey="cust_import_001"
  apiUrl="https://api.yourapp.com"
  onComplete={(data) => console.log(data)}
/>
```

--------------------------------

### Implement CSVImporter Component

Source: https://docs.importcsv.com/getting-started

A complete example showing how to define a Zod schema and use the CSVImporter component in a React application.

```javascript
'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={(result) => {
          // result.rows is typed: { name: string; email: string; company?: string }[]
          console.log(`Imported ${result.rows.length} customers`);

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

--------------------------------

### Fetching dynamic columns from backend

Source: https://docs.importcsv.com/configuration/dynamic-columns

Example of fetching dynamic columns from a backend API based on customerId and passing them to the CSVImporter component. Includes loading state handling.

```tsx
import { useState, useEffect } from 'react';
import { CSVImporter, Column } from '@importcsv/react';

function ImporterWithCustomFields({ customerId }: { customerId: string }) {
  const [dynamicColumns, setDynamicColumns] = useState<Column[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadFields() {
      const response = await fetch(`/api/customers/${customerId}/import-fields`);
      const fields = await response.json();
      setDynamicColumns(fields);
      setLoading(false);
    }
    loadFields();
  }, [customerId]);

  if (loading) return <div>Loading...</div>;

  return (
    <CSVImporter
      columns={predefinedColumns}
      dynamicColumns={dynamicColumns}
      onComplete={handleImport}
    />
  );
}
```

--------------------------------

### Create Importer Request Body

Source: https://docs.importcsv.com/self-hosting/api-reference

Example request body for creating an importer. Returns the created importer object with generated ID and key.

```json
{
  "name": "Customer Import",
  "description": "Import customer data",
  "fields": [
    {
      "name": "email",
      "display_name": "Email Address",
      "type": "email",
      "validators": [
        {
          "type": "required",
          "message": "Email is required"
        }
      ],
      "transformations": [
        { "type": "trim" },
        { "type": "lowercase" }
      ],
      "options": null
    }
  ],
  "webhook_url": "https://example.com/webhook",
  "webhook_enabled": true,
  "include_data_in_webhook": false,
  "webhook_data_sample_size": 10,
  "include_unmatched_columns": false,
  "filter_invalid_rows": false,
  "disable_on_invalid_rows": false,
  "dark_mode": false
}
```

--------------------------------

### Webhook event: import.started

Source: https://docs.importcsv.com/self-hosting/api-reference

Webhook payload sent when an import starts. Contains event type, importer ID, import ID, and timestamp.

```json
{
  "event": "import.started",
  "importer_id": "uuid",
  "import_id": "uuid",
  "timestamp": "2024-01-01T00:00:00Z"
}
```

--------------------------------

### Create Import Response

Source: https://docs.importcsv.com/self-hosting/api-reference

Example of the response from creating an import job. Returns the import ID, importer ID, status (processing), and created timestamp.

```json
{
  "id": "uuid",
  "importer_id": "uuid",
  "status": "processing",
  "created_at": "2024-01-01T00:00:00Z"
}
```

--------------------------------

### CSVImporter dynamicColumns output structure

Source: https://docs.importcsv.com/reference/api

An example of the resulting data object structure when using dynamic columns and unmatched columns.

```json
// Example result structure
{
  rows: [
    {
      name: 'John Doe',           // Predefined column
      email: 'john@example.com',  // Predefined column
      _custom_fields: {           // Dynamic columns
        location: 'New York',
        department: 'Engineering'
      },
      _unmatched: {               // Unmatched columns (if includeUnmatchedColumns=true)
        extra_col: 'some value'
      }
    }
  ],
  columns: {
    predefined: [{ id: 'name', label: 'Name' }, { id: 'email', label: 'Email' }],
    dynamic: [{ id: 'location', label: 'Location' }, { id: 'department', label: 'Department' }],
    unmatched: ['extra_col']
  }
}
```

--------------------------------

### Webhook payload example

Source: https://docs.importcsv.com/self-hosting/admin-dashboard

Example JSON payload sent to a webhook when an import event occurs. Contains event type, importer ID, import ID, row count, and timestamp.

```json
{
  "event": "import.completed",
  "importer_id": "uuid",
  "import_id": "uuid",
  "num_rows": 100,
  "timestamp": "2024-01-01T00:00:00Z"
}
```

--------------------------------

### Example JSON Response

Source: https://docs.importcsv.com/reference/api

A sample JSON object representing the structure of imported CSV data.

```json
{
  "num_rows": 2,
  "num_columns": 2,
  "columns": [
    { "id": "name", "label": "Name" },
    { "id": "email", "label": "Email" }
  ],
  "rows": [
    {
      "index": 0,
      "values": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    },
    {
      "index": 1,
      "values": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    }
  ]
}
```

--------------------------------

### Local Mode CSVImporter Configuration

Source: https://docs.importcsv.com/self-hosting/comparison

Example of configuring the CSVImporter component directly in frontend code using the columns prop.

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

--------------------------------

### Example usage of CSVImporter with onComplete

Source: https://docs.importcsv.com/reference/api

Shows how to use the CSVImporter component with a Zod schema and dynamic columns. The onComplete callback receives an ImportResult typed with the schema, allowing access to validated rows and column metadata.

```tsx
import { CSVImporter, ImportResult } from '@importcsv/react';
import { z } from 'zod';

const schema = z.object({
  name: z.string(),
  email: z.string().email()
});

type User = z.infer<typeof schema>;

<CSVImporter
  schema={schema}
  dynamicColumns={[{ id: 'department', label: 'Department' }]}
  onComplete={(result: ImportResult<User>) => {
    // Access validated rows
    result.rows.forEach(row => {
      console.log(row.name, row.email);           // Typed from schema
      console.log(row._custom_fields?.department); // Dynamic columns
    });

    // Access column metadata
    console.log(`Predefined: ${result.columns.predefined.length}`);
    console.log(`Dynamic: ${result.columns.dynamic.length}`);
    console.log(`Unmatched: ${result.columns.unmatched.join(', ')}`);
  }}
/>
```

--------------------------------

### shadcn/ui integration with @importcsv/react/headless

Source: https://docs.importcsv.com/advanced/headless

Use this example to integrate the headless CSV importer with shadcn/ui components. It defines a Zod schema for contact data, uses CSV.Root with an upload trigger and validator, and displays validation errors in a styled card. The validator shows a 'Validate' button that is disabled while validating and lists errors with row and column details.

```jsx
import * as CSV from '@importcsv/react/headless';
import { Button } from '@/components/ui/button';
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card';
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(1),
  email: z.string().email()
});

function ContactImporter() {
  return (
    <CSV.Root schema={schema} onComplete={handleComplete}>
      <Card>
        <CardHeader>
          <CardTitle>Import Contacts</CardTitle>
        </CardHeader>
        <CardContent className="space-y-4">
          <CSV.UploadTrigger asChild>
            <Button className="w-full">Upload CSV File</Button>
          </CSV.UploadTrigger>

          <CSV.Validator>
            {({ errors, validate, isValidating }) => (
              <div className="space-y-4">
                <Button
                  onClick={validate}
                  disabled={isValidating}
                  variant="secondary"
                >
                  {isValidating ? 'Validating...' : 'Validate'}
                </Button>

                {errors.length > 0 && (
                  <div className="rounded-lg border border-red-200 bg-red-50 p-4">
                    <h4 className="font-semibold text-red-800">
                      {errors.length} Errors Found
                    </h4>
                    <div className="mt-2 space-y-1">
                      {errors.map((error, i) => (
                        <p key={i} className="text-sm text-red-700">
                          Row {error.row + 1} - {error.column}: {error.message}
                        </p>
                      ))}
                    </div>
                  </div>
                )}
              </div>
            )}
          </CSV.Validator>
        </CardContent>
      </Card>
    </CSV.Root>
  );
}
```

--------------------------------

### Initialize database with Alembic

Source: https://docs.importcsv.com/self-hosting/getting-started

Runs database migrations using Alembic.

```bash
# Run migrations
alembic upgrade head
```

--------------------------------

### Sample CSV

Source: https://docs.importcsv.com/configuration/basic

Provides a sample CSV file with headers Name, Email, and Phone, showcasing the expected data format for the importer.

```csv
Name,Email,Phone
John Doe,john@example.com,555-0100
Jane Smith,jane@example.com,555-0101
```

--------------------------------

### Migration Path Code Update

Source: https://docs.importcsv.com/self-hosting/comparison

Shows the transition from a local configuration to a backend-driven configuration.

```javascript
// Before: <CSVImporter columns={[...]} onComplete={handleComplete} />
// After: <CSVImporter importerKey="your-key" apiUrl="https://..." onComplete={handleComplete} />
```

--------------------------------

### Get Importer GET /importers/{importer_id}

Source: https://docs.importcsv.com/self-hosting/api-reference

Endpoint to fetch a specific importer by its ID. The response is a single importer object.

```http
GET /importers/{importer_id}
```

--------------------------------

### Get Import Status GET /imports/{import_id}

Source: https://docs.importcsv.com/self-hosting/api-reference

Endpoint to check the status of an import job. Returns details including status, row counts, and possible error messages.

```http
GET /imports/{import_id}
```

--------------------------------

### Configure CSVImporter for Local Mode

Source: https://docs.importcsv.com/advanced/ai-features

Run the importer without a cloud connection. AI transformations are unavailable, but column mapping via string similarity and Zod schema validation remain functional.

```javascript
// Local mode - no backendUrl needed
<CSVImporter
  schema={schema}
  onComplete={handleComplete}
/>
```

--------------------------------

### CSVImporter invalidRowHandling configurations

Source: https://docs.importcsv.com/reference/api

Examples of the three modes for handling validation errors: 'block' (default), 'exclude', and 'include'.

```javascript
// Strict mode - blocks import on any error (default)
<CSVImporter
  columns={columns}
  invalidRowHandling="block"
  onComplete={(data) => console.log(data)}
/>
```

```javascript
// Filter mode - imports only valid rows
<CSVImporter
  columns={columns}
  invalidRowHandling="exclude"
  onComplete={(data) => {
    // data contains only rows that passed validation
    console.log(`Imported ${data.num_rows} valid rows`);
  }}
/>
```

```javascript
// Permissive mode - imports everything with warnings
<CSVImporter
  columns={columns}
  invalidRowHandling="include"
  onComplete={(data) => {
    // data contains all rows, check for errors separately
    console.log(`Imported ${data.num_rows} rows (may include invalid data)`);
  }}
/>
```

--------------------------------

### Configure CSVImporter with Cloud Mode

Source: https://docs.importcsv.com/advanced/ai-features

Connect to the cloud backend by providing a backendUrl and importerKey to enable AI-powered features.

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

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

<CSVImporter
  schema={schema}
  backendUrl="https://api.importcsv.com"
  importerKey="your-importer-key"
  onComplete={handleComplete}
/>
```

--------------------------------

### GET /importers

Source: https://docs.importcsv.com/self-hosting/api-reference

Retrieves all importers for the authenticated user. Supports pagination via skip and limit query parameters.

```APIDOC
## GET /importers

### Description
Get all importers for the authenticated user.

### Method
GET

### Endpoint
/importers

### Parameters
#### Query Parameters
- **skip** (integer) - Optional - Number of records to skip (default: 0)
- **limit** (integer) - Optional - Maximum records to return (default: 100)

### Response
#### Success Response (200)
- **id** (string) - Importer ID
- **name** (string) - Importer name
- **key** (string) - Importer key
- **description** (string) - Description
- **fields** (array) - Field definitions
- **webhook_url** (string) - Webhook URL
- **webhook_enabled** (boolean) - Whether webhook is enabled
- **include_data_in_webhook** (boolean) - Whether to include data in webhook
- **webhook_data_sample_size** (integer) - Sample size for webhook data
- **include_unmatched_columns** (boolean) - Whether to include unmatched columns
- **filter_invalid_rows** (boolean) - Whether to filter invalid rows
- **disable_on_invalid_rows** (boolean) - Whether to disable on invalid rows
- **dark_mode** (boolean) - Dark mode setting
- **created_at** (string) - Creation timestamp

#### Response Example
```json
[
  {
    "id": "uuid",
    "name": "Customer Import",
    "key": "uuid-key-string",
    "description": "Import customer data",
    "fields": [],
    "webhook_url": "https://example.com/webhook",
    "webhook_enabled": true,
    "include_data_in_webhook": false,
    "webhook_data_sample_size": 10,
    "include_unmatched_columns": false,
    "filter_invalid_rows": false,
    "disable_on_invalid_rows": false,
    "dark_mode": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```
```

--------------------------------

### Backend environment configuration (.env)

Source: https://docs.importcsv.com/self-hosting/getting-started

Defines database, Redis, security, Clerk, webhook, and optional AI settings. The OPENAI_API_KEY enables smart column mapping and natural language transformations.

```env
# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/importcsv

# Redis Queue
REDIS_URL=redis://localhost:6379/0
RQ_DEFAULT_TIMEOUT=360
RQ_IMPORT_QUEUE=imports

# Security
SECRET_KEY=your-secret-key-at-least-32-characters

# Clerk Authentication
CLERK_WEBHOOK_SECRET=whsec_xxxxx
CLERK_JWT_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----
YOUR_PUBLIC_KEY_HERE
-----END PUBLIC KEY-----

# Webhook (optional)
WEBHOOK_SECRET=your-webhook-secret

# AI Features (optional but recommended)
OPENAI_API_KEY=sk-xxxxx  # Enables smart column mapping and natural language transformations
```

--------------------------------

### Post-Stage Transformer Example

Source: https://docs.importcsv.com/configuration/transformations

Uses `stage: 'post'` (the default) on a normalize_phone transformer to format the phone number after validation has passed.

```javascript
transformations: [
  // Format phone number after it's validated
  { type: 'normalize_phone', stage: 'post' }
]
```

--------------------------------

### Theming: Customize CSVImporter with theme and primaryColor

Source: https://docs.importcsv.com/getting-started/react

Use the theme prop to apply a predefined theme (e.g., 'dark') and primaryColor to match your brand. Available themes include 'default', 'dark', 'minimal', 'modern', 'compact', or a custom ThemeConfig object.

```jsx
<CSVImporter
  schema={schema}
  onComplete={handleComplete}
  theme="dark"
  primaryColor="#10b981"
/>
```

--------------------------------

### GET /imports/{import_id}

Source: https://docs.importcsv.com/self-hosting/api-reference

Checks the status of an import job. Returns detailed information including row counts and errors.

```APIDOC
## GET /imports/{import_id}

### Description
Check the status of an import job.

### Method
GET

### Endpoint
/imports/{import_id}

### Parameters
#### Path Parameters
- **import_id** (string) - Required - The ID of the import job.

### Response
#### Success Response (200)
- **id** (string) - Import job ID
- **importer_id** (string) - Importer ID
- **status** (string) - Status of the import job (pending, processing, completed, failed)
- **num_rows** (integer) - Number of rows processed
- **num_errors** (integer) - Number of errors
- **errors** (array) - List of errors
- **created_at** (string) - Creation timestamp
- **completed_at** (string) - Completion timestamp

#### Response Example
```json
{
  "id": "uuid",
  "importer_id": "uuid",
  "status": "completed",
  "num_rows": 100,
  "num_errors": 2,
  "errors": [
    {
      "row": 5,
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:01:00Z"
}
```
```

--------------------------------

### CSVImporter dynamicColumns configuration

Source: https://docs.importcsv.com/reference/api

Shows how to use dynamicColumns to handle customer-specific fields that are resolved at runtime.

```javascript
// Fetch customer-specific fields at runtime
const customerFields = await fetchCustomerFields(customerId);
// Returns: [{ id: 'location', label: 'Location' }, { id: 'department', label: 'Department' }]

<CSVImporter
  columns={[
    { id: 'name', label: 'Name', validators: [{ type: 'required' }] },
    { id: 'email', label: 'Email', type: 'email' },
  ]}
  dynamicColumns={customerFields}
  onComplete={(result) => {
    result.rows.forEach(row => {
      // Predefined fields at top level
      console.log(row.name, row.email);

      // Dynamic fields nested under _custom_fields
      console.log(row._custom_fields?.location);
      console.log(row._custom_fields?.department);
    });
  }}
/>
```

--------------------------------

### Configure CSVImporter in Backend Mode

Source: https://docs.importcsv.com/reference/api

Use the importerKey and backendUrl props to enable backend mode, which offloads schema management and data processing to your server.

```jsx
<CSVImporter
  importerKey="your-importer-key"
  backendUrl="https://api.yoursite.com"
  onComplete={() => {
    // In backend mode, this is called when the import completes
    // but data is sent to your backend, not passed here
    console.log('Import completed - data sent to backend');
  }}
/>
```

--------------------------------

### POST /importers

Source: https://docs.importcsv.com/self-hosting/api-reference

Creates a new importer configuration. The request body includes name, description, fields, and webhook settings.

```APIDOC
## POST /importers

### Description
Create a new importer configuration.

### Method
POST

### Endpoint
/importers

### Parameters
#### Request Body
- **name** (string) - Required - Importer name
- **description** (string) - Optional - Description
- **fields** (array) - Required - Field definitions
- **webhook_url** (string) - Optional - Webhook URL
- **webhook_enabled** (boolean) - Optional - Whether webhook is enabled
- **include_data_in_webhook** (boolean) - Optional - Whether to include data in webhook
- **webhook_data_sample_size** (integer) - Optional - Sample size for webhook data
- **include_unmatched_columns** (boolean) - Optional - Whether to include unmatched columns
- **filter_invalid_rows** (boolean) - Optional - Whether to filter invalid rows
- **disable_on_invalid_rows** (boolean) - Optional - Whether to disable on invalid rows
- **dark_mode** (boolean) - Optional - Dark mode setting

### Request Example
```json
{
  "name": "Customer Import",
  "description": "Import customer data",
  "fields": [
    {
      "name": "email",
      "display_name": "Email Address",
      "type": "email",
      "validators": [
        {
          "type": "required",
          "message": "Email is required"
        }
      ],
      "transformations": [
        { "type": "trim" },
        { "type": "lowercase" }
      ],
      "options": null
    }
  ],
  "webhook_url": "https://example.com/webhook",
  "webhook_enabled": true,
  "include_data_in_webhook": false,
  "webhook_data_sample_size": 10,
  "include_unmatched_columns": false,
  "filter_invalid_rows": false,
  "disable_on_invalid_rows": false,
  "dark_mode": false
}
```

### Response
Returns the created importer object with generated ID and key.
```

--------------------------------

### React CSVImporter component usage

Source: https://docs.importcsv.com/self-hosting/admin-dashboard

Example of using the CSVImporter component in a React application. Requires importerKey and apiUrl props, and an onComplete callback.

```jsx
<CSVImporter
  importerKey="your-importer-key"
  apiUrl="http://your-backend-url"
  onComplete={(data) => console.log(data)}
/>
```

--------------------------------

### CSVImporter with Zod Schema

Source: https://docs.importcsv.com/reference/api

Shows how to use a Zod schema with the CSVImporter component to validate imported CSV data and get typed results.

```APIDOC
## CSVImporter with Zod Schema

### Description
Use a Zod schema to define validation rules for the CSV importer. The schema automatically provides TypeScript inference for the imported data.

### Usage
```jsx
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.string().email('Invalid email'),
  age: z.number().int().positive().optional()
});

<CSVImporter
  schema={schema}
  onComplete={(data) => {
    // data is typed as: { name: string; email: string; age?: number }[]
  }}
/>
```

### Parameters
- **schema** (ZodSchema) - Required - The Zod schema used for validation and type inference.
- **onComplete** (function) - Required - Callback invoked with the validated data array.

### Response
- **data** (Array) - The validated data array with inferred TypeScript types.
```

--------------------------------

### GET /importers/{importer_id}

Source: https://docs.importcsv.com/self-hosting/api-reference

Retrieves a specific importer by its ID. Returns the full importer configuration including fields, webhook settings, and timestamps.

```APIDOC
## GET /importers/{importer_id}

### Description
Get a specific importer by ID.

### Method
GET

### Endpoint
/importers/{importer_id}

### Parameters
#### Path Parameters
- **importer_id** (string) - Required - The ID of the importer to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Importer ID
- **name** (string) - Importer name
- **key** (string) - Importer key
- **description** (string) - Description
- **fields** (array) - Field definitions
- **webhook_url** (string) - Webhook URL
- **webhook_enabled** (boolean) - Whether webhook is enabled
- **include_data_in_webhook** (boolean) - Whether to include data in webhook
- **webhook_data_sample_size** (integer) - Sample size for webhook data
- **include_unmatched_columns** (boolean) - Whether to include unmatched columns
- **filter_invalid_rows** (boolean) - Whether to filter invalid rows
- **disable_on_invalid_rows** (boolean) - Whether to disable on invalid rows
- **dark_mode** (boolean) - Dark mode setting
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp

#### Response Example
```json
{
  "id": "uuid",
  "name": "Customer Import",
  "key": "uuid-key-string",
  "description": "Import customer data",
  "fields": [
    {
      "name": "email",
      "display_name": "Email Address",
      "id": "email",
      "label": "Email Address",
      "type": "email",
      "validators": [
        {
          "type": "required",
          "message": "Email is required"
        }
      ],
      "transformations": [
        { "type": "trim" },
        { "type": "lowercase" }
      ],
      "options": null
    }
  ],
  "webhook_url": "https://example.com/webhook",
  "webhook_enabled": true,
  "include_data_in_webhook": false,
  "webhook_data_sample_size": 10,
  "include_unmatched_columns": false,
  "filter_invalid_rows": false,
  "disable_on_invalid_rows": false,
  "dark_mode": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```
```

--------------------------------

### Basic headless CSV importer with validation

Source: https://docs.importcsv.com/advanced/headless

Shows how to use headless components (Root, UploadTrigger, Validator) with a Zod schema to build a custom importer. The Validator exposes errors, validate, and isValidating for custom UI.

```tsx
import * as CSV from '@importcsv/react/headless';
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(1),
  email: z.string().email()
});

function CustomImporter() {
  return (
    <CSV.Root schema={schema} onComplete={(data) => console.log(data)}>
      <CSV.UploadTrigger>Upload CSV</CSV.UploadTrigger>
      <CSV.Validator>
        {({ errors, validate, isValidating }) => (
          <div>
            <button onClick={validate} disabled={isValidating}>
              Validate
            </button>
            {errors.map((error, i) => (
              <div key={i}>
                Row {error.row + 1}, {error.column}: {error.message}
              </div>
            ))}
          </div>
        )}
      </CSV.Validator>
    </CSV.Root>
  );
}
```

--------------------------------

### Preset Themes: Minimal, Gradient, Corporate

Source: https://docs.importcsv.com/configuration/theming

Use these preset theme objects to quickly apply a consistent look. The Minimal theme uses sharp corners and black primary color, Gradient uses a purple-pink gradient, and Corporate uses Arial font with blue primary. Each object can be passed to the customStyles prop.

```javascript
// Minimal
const minimal = {
  'border-radius': '0px',
  'color-primary': '#000000',
  'color-border': '#000000'
};

// Gradient
const gradient = {
  'border-radius': '16px',
  'color-primary': '#667EEA',
  'color-primary-hover': '#5A67D8',
  'color-secondary': '#ED64A6'
};

// Corporate
const corporate = {
  'font-family': 'Arial, sans-serif',
  'border-radius': '4px',
  'color-primary': '#0066CC',
  'color-border': '#CCCCCC'
};
```

--------------------------------

### onComplete Callback

Source: https://docs.importcsv.com/reference/api

The onComplete callback receives an ImportResult object containing the imported rows and column metadata. This snippet shows the TypeScript interface and an example usage with the CSVImporter component.

```APIDOC
## onComplete Callback

### Description
The `onComplete` callback receives an `ImportResult` object containing the imported rows and column metadata.

### Interface
```typescript
interface ImportResult<T = Record<string, unknown>> {
  rows: Array<T & {
    _custom_fields?: Record<string, unknown>;  // Dynamic column values
    _unmatched?: Record<string, unknown>;      // Unmapped CSV columns
  }>;
  columns: {
    predefined: Column[];   // Columns from `columns` prop
    dynamic: Column[];      // Columns from `dynamicColumns` prop
    unmatched: string[];    // CSV column names that weren't mapped
  };
}
```

### Example Usage
```tsx
import { CSVImporter, ImportResult } from '@importcsv/react';
import { z } from 'zod';

const schema = z.object({
  name: z.string(),
  email: z.string().email()
});

type User = z.infer<typeof schema>;

<CSVImporter
  schema={schema}
  dynamicColumns={[{ id: 'department', label: 'Department' }]}
  onComplete={(result: ImportResult<User>) => {
    // Access validated rows
    result.rows.forEach(row => {
      console.log(row.name, row.email);           // Typed from schema
      console.log(row._custom_fields?.department); // Dynamic columns
    });

    // Access column metadata
    console.log(`Predefined: ${result.columns.predefined.length}`);
    console.log(`Dynamic: ${result.columns.dynamic.length}`);
    console.log(`Unmatched: ${result.columns.unmatched.join(', ')}`);
  }}
/>
```

### Row Structure
| Field | Type | Description |
| --- | --- | --- |
| `[column_id]` | `any` | Values from predefined columns (top-level) |
| `_custom_fields` | `Record<string, unknown>` | Values from `dynamicColumns` prop |
| `_unmatched` | `Record<string, unknown>` | Values from unmapped CSV columns (when `includeUnmatchedColumns` is true) |

### Columns Metadata
| Field | Type | Description |
| --- | --- | --- |
| `predefined` | `Column[]` | Columns defined via `columns` or `schema` prop |
| `dynamic` | `Column[]` | Columns from `dynamicColumns` prop |
| `unmatched` | `string[]` | CSV header names that weren't mapped to any column |
```

--------------------------------

### Implement Dynamic Columns with CSVImporter

Source: https://docs.importcsv.com/configuration/dynamic-columns

Demonstrates how to define a base schema and inject additional customer-specific fields into the CSVImporter component. Dynamic fields are accessed via the _custom_fields object in the onComplete callback.

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

// Your predefined schema - same for all customers
const columns = [
  { id: 'name', label: 'Name', validators: [{ type: 'required' }] },
  { id: 'email', label: 'Email', type: 'email' },
];

// Customer-specific fields fetched at runtime
const customerFields = [
  { id: 'department', label: 'Department' },
  { id: 'cost_center', label: 'Cost Center' },
];

<CSVImporter
  columns={columns}
  dynamicColumns={customerFields}
  onComplete={(result) => {
    // Predefined fields at top level
    console.log(result.rows[0].name);
    console.log(result.rows[0].email);

    // Dynamic fields nested under _custom_fields
    console.log(result.rows[0]._custom_fields?.department);
    console.log(result.rows[0]._custom_fields?.cost_center);
  }}
/>
```

--------------------------------

### Apply Custom Refinements

Source: https://docs.importcsv.com/configuration/schemas

Shows how to use .refine() to implement custom validation logic that goes beyond basic type checking, such as password complexity or domain restrictions.

```javascript
const schema = z.object({
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .refine(
      (val) => /[A-Z]/.test(val),
      'Password must contain at least one uppercase letter'
    )
    .refine(
      (val) => /[0-9]/.test(val),
      'Password must contain at least one number'
    ),

  email: z.string().email().refine(
    (email) => !email.endsWith('@example.com'),
    'Example.com emails are not allowed'
  ),

  age: z.number().refine(
    (age) => age >= 18,
    { message: 'Must be 18 or older', path: ['age'] }
  )
});
```
Tokens:
Raw