Import wizard
ProA CSV import that maps columns with confidence, highlights bad cells, rolls the issue counts down as you fix them, and imports in batches.
- Bringing contacts or records in from CSV exports.
- Onboarding that needs a customer's existing data.
- Admin tools that bulk update records.
- Uploading files as attachments; use file-upload.
- Mapping only, without validation; use import-mapper.
- Live syncs with other tools; use integrations.
Installation
Pro source and install commands unlock with a Pro plan.
Usage
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.
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`)} /> );}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.
targetsImportTarget[]contact fieldsFields to map to, each with exact and synonym header names, a validator, an optional safe fix, and an optional value sniffer.existingEmailsSet<string>sample setEmails 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.batchSizenumber5Rows per batch.noun[string, string]["contact", "contacts"]Singular and plural names used in copy.classNamestring–Extra class on the root.- EnterorSpace
- Opens the file picker from the drop zone, or edits a review cell.
- Enter
- Saves a cell edit.
- Escape
- Cancels a cell edit.
- 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.
- 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.
- The stepper shows only the current label on phones.
- Mapping rows stack below 560px.
- The review table scrolls sideways inside its card.
- Validation is memoized and runs over rows times mapped columns.
- Only rows in view animate; the preview shows five rows.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- 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.
The full library index for assistants is at /llms.txt.