# Import wizard

> A CSV import that maps columns with confidence, highlights bad cells, rolls the issue counts down as you fix them, and imports in batches.

- Type: Block
- Page: https://uiarc.dev/components/blocks/import-wizard
- Markdown: https://uiarc.dev/components/blocks/import-wizard/markdown

- Access: Arc Pro
- Registry id: `import-wizard`
- Source file: `registry/blocks/import-wizard/import-wizard.tsx`
- Built from: File dropzone, Select, Segmented control, Progress, Animated counter, Inline edit
- Keywords: csv import, data import, column mapping, spreadsheet upload, validation, import wizard, bulk import

Use this wherever people bring data in from a spreadsheet. Describe your fields as targets with validators and safe fixes, send batches to your API through onImportBatch, and read the totals in onComplete; the preview simulates the import.

## When to use

- Bringing contacts or records in from CSV exports.
- Onboarding that needs a customer's existing data.
- Admin tools that bulk update records.

## When not to use

- Uploading files as attachments; use file-upload.
- Mapping only, without validation; use import-mapper.
- Live syncs with other tools; use integrations.

## Installation

Import wizard is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/import-wizard
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
import { ImportWizard } from "@/components/arc/blocks/import-wizard/import-wizard";

export function ImportContacts() {
  return (
    <ImportWizard
      batchSize={200}
      onImportBatch={records => fetch("/api/contacts/bulk", { method: "POST", body: JSON.stringify(records) })}
      onComplete={({ created, updated }) => toast(`${created + updated} contacts imported`)}
    />
  );
}
```

## API reference

### ImportWizard

A four step CSV import: drop a file and preview it, map columns with a confidence for every automatic match, fix invalid cells inline while the issue counts roll down, then import in batches and read the summary. The steps share one card that springs to each step's height.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `targets` | `ImportTarget[]` | `contact fields` | Fields to map to, each with exact and synonym header names, a validator, an optional safe fix, and an optional value sniffer. |
| `existingEmails` | `Set<string>` | `sample set` | Emails that already exist; matching rows count as updates in the summary. |
| `onImportBatch` | `(records: ImportRecord[]) => void \| Promise<void>` | – | Imports one batch. Defaults to a simulation. |
| `onComplete` | `(result: { created: number; updated: number; skipped: number }) => void` | – | Called once every batch is done. |
| `batchSize` | `number` | `5` | Rows per batch. |
| `noun` | `[string, string]` | `["contact", "contacts"]` | Singular and plural names used in copy. |
| `className` | `string` | – | Extra class on the root. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter or Space | Opens the file picker from the drop zone, or edits a review cell. |
| Enter | Saves a cell edit. |
| Escape | Cancels a cell edit. |

## Accessibility

- The drop zone is a label for a real file input, so keyboard and screen reader users can choose a file.
- Each mapping select is named after its source column; confidence is written as a percentage, not only a bar.
- Invalid cells carry the error in their button label; issue counts update in a polite live region.
- Import progress is a progressbar with current and total values.

## Motion

- Steps slide and blur in the direction of travel while the card springs to the new height.
- Mapping resolves one column at a time and each confidence meter fills on the smooth spring.
- Auto fix applies one cell every 90ms so counts roll down in a cascade; fixed rows glow green and slide out of the issues view.
- Summary numbers count up once. Reduced motion shows final values at once.

## Responsive behavior

- The stepper shows only the current label on phones.
- Mapping rows stack below 560px.
- The review table scrolls sideways inside its card.

## Performance

- Validation is memoized and runs over rows times mapped columns.
- Only rows in view animate; the preview shows five rows.

## Notes for AI

- Choose this for importing contacts, products, users or any tabular data from spreadsheets.
- Describe your schema as targets; validators return a message and fix returns a safe cleaned value, which powers the auto fix button.
- Rows with unresolved issues are skipped, not blocked, so people can import the good rows now.
- Parsing handles quoted fields; for files over 5,000 rows parse on the server or in a worker.

## Related

- [File upload](https://uiarc.dev/components/blocks/file-upload/markdown): A complete file selection flow with constraints, progress, and error feedback.
- [File dropzone](https://uiarc.dev/components/file-dropzone/markdown): A generous target for dropping one or more files.
- [Multi-step form](https://uiarc.dev/components/blocks/multi-step-form/markdown): A guided form that presents one decision at a time and preserves progress.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

## Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt