Examples

Common use cases and implementation patterns.

Basic Contact Import

import { ImportWidget } from '@importkit/react'

function ContactImporter() {
  const handleComplete = async (data) => {
    // data is an array of validated rows
    await fetch('/api/contacts', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ contacts: data }),
    })
  }

  return (
    <ImportWidget
      apiKey="ik_live_..."
      fields={[
        { name: 'email', label: 'Email', type: 'email', required: true },
        { name: 'first_name', label: 'First Name', required: true },
        { name: 'last_name', label: 'Last Name', required: true },
        { name: 'phone', label: 'Phone' },
        { name: 'company', label: 'Company' },
      ]}
      onComplete={handleComplete}
    />
  )
}

Product Catalog Import

<ImportWidget
  apiKey="ik_live_..."
  fields={[
    { name: 'sku', label: 'SKU', required: true },
    { name: 'name', label: 'Product Name', required: true },
    {
      name: 'price',
      label: 'Price',
      type: 'number',
      validate: [{ type: 'min', value: 0 }]
    },
    {
      name: 'category',
      label: 'Category',
      type: 'enum',
      enum: {
        values: ['electronics', 'clothing', 'home', 'other'],
        hints: [
          'tech, gadgets, devices',
          'apparel, fashion, wear',
          'furniture, decor, kitchen',
          'misc, miscellaneous'
        ]
      }
    },
    { name: 'description', label: 'Description' },
  ]}
  onComplete={(data) => saveProducts(data)}
/>

Advanced Validation

Use validation rules to enforce data quality before import. All 8 rule types can be combined on a single field.

import { ImportWidget } from '@importkit/react'

const fields = [
  {
    name: 'email',
    label: 'Email Address',
    required: true,
    type: 'email' as const,
    validate: [{ type: 'email' as const }],
  },
  {
    name: 'age',
    label: 'Age',
    type: 'number' as const,
    validate: [
      { type: 'number' as const },
      { type: 'min' as const, value: 18, message: 'Must be 18 or older' },
      { type: 'max' as const, value: 120, message: 'Invalid age' },
    ],
  },
  {
    name: 'product_code',
    label: 'Product Code',
    required: true,
    validate: [
      { type: 'regex' as const, value: '^[A-Z]{2}\\d{4}$', message: 'Format: XX0000' },
    ],
  },
  {
    name: 'username',
    label: 'Username',
    required: true,
    validate: [
      { type: 'minLength' as const, value: 3, message: 'At least 3 characters' },
      { type: 'maxLength' as const, value: 20, message: 'Max 20 characters' },
    ],
  },
  {
    name: 'role',
    label: 'Role',
    required: true,
    validate: [
      { type: 'oneOf' as const, value: ['admin', 'editor', 'viewer'] },
    ],
  },
]

// Validation errors appear inline in the preview table.
// Users can click any cell to edit and fix errors before importing.
<ImportWidget
  apiKey="ik_live_..."
  fields={fields}
  onComplete={(data) => saveUsers(data)}
/>

Webhook Handling

On Pro and Enterprise plans, ImportKit sends a POST request to your configured webhook endpoints when an import completes. Set up endpoints in the dashboard under Webhooks.

// Your server endpoint that receives ImportKit webhooks
// e.g. Express / Next.js API route

app.post('/webhooks/importkit', (req, res) => {
  const { event, importId, rowCount, templateName, timestamp } = req.body

  if (event === 'import.completed') {
    console.log(`Import ${importId}: ${rowCount} rows imported`)
    // Trigger downstream processing, notifications, etc.
  }

  res.status(200).json({ received: true })
})

Webhook payload fields:

• event — always "import.completed"
• importId — unique import identifier (e.g. imp_abc123)
• rowCount — number of rows imported
• templateName — name of the template used (if any)
• timestamp — ISO 8601 timestamp

Using Templates

Save field configurations in the dashboard and reference them by ID:

// Fields are loaded from your saved template
<ImportWidget
  apiKey="ik_live_..."
  templateId="tmpl_abc123"
  onComplete={handleComplete}
/>

With Error Handling

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

function ImporterWithErrors() {
  const [error, setError] = useState(null)
  const [success, setSuccess] = useState(false)

  return (
    <div>
      {error && (
        <div className="alert alert-error">
          {error.message}
        </div>
      )}

      {success ? (
        <div className="alert alert-success">
          Import completed successfully!
        </div>
      ) : (
        <ImportWidget
          apiKey="ik_live_..."
          fields={fields}
          onComplete={(data) => {
            saveData(data)
            setSuccess(true)
          }}
          onError={(err) => setError(err)}
        />
      )}
    </div>
  )
}

Next.js App Router

// app/import/page.tsx
'use client'

import { ImportWidget } from '@importkit/react'

export default function ImportPage() {
  return (
    <div className="container mx-auto py-8">
      <h1>Import Data</h1>
      <ImportWidget
        apiKey={process.env.NEXT_PUBLIC_IMPORTKIT_KEY!}
        fields={[
          { name: 'email', label: 'Email', type: 'email', required: true },
          { name: 'name', label: 'Name', required: true },
        ]}
        onComplete={async (data) => {
          const res = await fetch('/api/import', {
            method: 'POST',
            body: JSON.stringify(data),
          })
          if (res.ok) {
            window.location.href = '/success'
          }
        }}
      />
    </div>
  )
}

Live Demo

Try the widget at demo.importkit.app