CSV Import React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

CSV Import is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import CsvImport from @/components/ui/csv-import.

import { CsvImport, type ImportField } from "@/components/ui/csv-import"

const FIELDS: ImportField[] = [
  { id: "company", label: "Company", required: true, aliases: ["Company name", "Customer"] },
  { id: "cui", label: "Tax ID (CUI)", type: "cui", aliases: ["CIF", "VAT ID"] },
  { id: "email", label: "Email", type: "email" },
  { id: "phone", label: "Phone", type: "phone" },
  { id: "balance", label: "Balance", type: "currency", aliases: ["Balance (USD)"] },
]

export function ImportCustomers({ existing }: { existing: string[] }) {
  return (
    <CsvImport
      fields={FIELDS}
      uniqueField="cui"
      existingKeys={existing}
      locale="en-US"
      dateFormat="MM/DD/YYYY"
      labels={{ upload: "File", map: "Columns", review: "Check", import: "Import" }}
      onImport={async (rows, { onProgress, signal }) => {
        const response = await fetch("/api/customers/import", { method: "POST", body: JSON.stringify(rows), signal })
        onProgress(rows.length)
        return response.json()
      }}
    />
  )
}

Props

• fields*
  ImportField[]

  What you import: { id, label, type?, required?, aliases?, options?, validate?, transform?, example?, description?, currency? }. type is text, number, currency, date, email, phone, cui, iban, cnp, boolean or select; aliases are other column names that mean the field; currency is the ISO code of a currency field's amounts (else the component's).

• onImport*
  (rows: Record<string, unknown>[], context: { strategy; onProgress: (done: number) => void; signal: AbortSignal; rows: ImportRow[] }) => Promise<ImportResult>

  Gets the valid, non-skipped rows with typed values (numbers, ISO dates, E.164 phones, formatted CUI and IBAN). Report progress, stop on the signal, resolve with { created, updated, skipped, failed?: { index, error }[] } where index is the file row from context.rows. A server can re-run the same checks with validateImportRows (see Parts).

• defaultStepdefault "upload"
  "upload" | "map" | "review" | "import"

  The step it opens on. The demo loads its sample file for any step past the upload.

• step
  "upload" | "map" | "review" | "import"

  The current step, controlled; pair it with onStepChange. A running import holds the wizard on its step.

• onStepChange
  (step: ImportStepId) => void

  Called on every step change.

• file
  File | null

  The picked file, controlled. Set it to start from a file you already have (a drop elsewhere on the page, a sample); pair it with onFileChange.

• defaultFile
  File | null

  A file to start with, uncontrolled.

• onFileChange
  (file: File | null) => void

  Called when a file is picked or removed.

• acceptdefault ".csv,.tsv,.txt,.xlsx"
  string

  File types the drop zone takes, like the native attribute; the hint under the zone lists them. Old .xls files are refused with errors.unsupported.

• maxFileSizedefault "20971520"
  number

  Bytes: 20 MB (20 × 1024 × 1024, so the hint reads a round "20 MB"). Bigger files are refused with errors.tooLarge; the hint under the drop zone shows the limit. 0 means no limit.

• maxRowsdefault 10000
  number

  Rows read per sheet. The rest is cut and a warning says so.

• uniqueFielddefault ""
  string

  The field that identifies a record (cui, email). Repeats inside the file become errors ("Duplicate of row 12"), rows found in existingKeys get an Exists badge, and the review shows the duplicates choice. The demo falls back to cui.

• duplicateStrategy
  "skip" | "update" | "create"

  Controlled: what happens to rows whose unique value already exists. Pair it with onDuplicateStrategyChange; the review's select changes it.

• defaultDuplicateStrategydefault "skip"
  "skip" | "update" | "create"

  What happens, while uncontrolled, to rows whose unique value already exists: left out (skip), passed on for an update, or added again (create). The review shows the choice once uniqueField is set; onImport gets it as context.strategy.

• onDuplicateStrategyChange
  (strategy: DuplicateStrategy) => void

  Called when the review's select changes.

• existingKeys
  string[] | Set<string>

  Values of uniqueField already in your system (compared without case and diacritics; CUIs with or without RO).

• allowSkipInvaliddefault true
  boolean

  Shows the "Skip rows with errors" switch (on). Off: every error must be fixed, or its row skipped by hand, before Import unlocks.

• inlineEditdefault true
  boolean

  Fix cells in the review: click a cell to edit it in place (a sheet on phones), and it is checked again at once.

• defaultHasHeaderdefault true
  boolean

  The starting value of the upload step's "The first row is a header" switch. Off reads the first row as data and names the columns "Column 1"... (labels.columnLabel); CUI, IBAN, CNP, email, phone and date columns are then matched by their values.

• templateFileNamedefault "import-template"
  string

  Name of the template CSV (the field labels and their examples, ";" separated where the locale writes decimal commas).

• delimiterdefault ""
  string

  Forces the CSV separator. Empty detects it among , ; tab and |.

• dateFormatdefault ""
  string

  A hint shown next to date fields in the mapping ("MM/DD/YYYY"). Parsing follows the locale, reads dotted dates day first, and accepts ISO and Excel dates.

• defaultCountrydefault "RO"
  string

  Country for phone numbers written without a + prefix (libphonenumber-js). Valid numbers are stored as E.164.

• currencydefault "USD"
  string

  ISO 4217 code for currency fields in the review ("$12,480.00"); a field's own currency wins. It only labels the amounts, nothing is converted.

• stepperdefault "horizontal"
  "horizontal" | "vertical" | "progress" | "dots" | "none"

  form-wizard's header from 768px up; phones always get the compact progress row.

• fullScreenOnMobiledefault true
  boolean

  Below 768px the wizard fills its container with a sticky header and footer and 48px buttons (form-wizard's). The container needs a height.

• sizedefault "md"
  "sm" | "md"

  Stepper markers, footer buttons, selects, switches and the filter.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The active step, the drop zone's drag tint, the switches, the progress bar and the primary button.

• localedefault ""
  string

  Parses and formats numbers, amounts and dates ("12,480.00" and 09/24/2026 in en-US, "12.480,00" and 24.09.2026 in ro-RO). Empty uses UIProvider's locale, then the browser's.

• labels
  Partial<CsvImportLabels>

  Every string, English by default: step titles and descriptions, the drop zone (drop, browse, tapTitle, dropHere, fileHint(types, max), fileRejected(names)), template, templateHint, parsing, removeFile, sheet, hasHeader, hasHeaderDescription, columnLabel, rows, columns, delimiter(d), noFile, noFileDescription, chooseFile, the mapping (column, doNotImport, searchColumns, autoMatched, sample, required, usedBy, missingRequired, matched, dateFormat, types), the review (all, errorsFilter, withErrors, valid, skipInvalid, skipInvalidDescription, duplicates, duplicatesDescription, strategies, exists, new, skippedRow, status, errorCount, row, missing, emptyValue, yes, no, skipRow, includeRow, fix, save, cancel, validating, fixToContinue, nothingToImport, noMatches, noMatchesDescription, showMore, tableCaption, toImport), the run (importing(done, total), ready, readySkipped, cancelled, complete, completeWithErrors, completeDescription, importFailed, retry), the summary (created, updated, skipped, failed, failedRows, moreInReport, fieldError(field, error), downloadReport, importMore, reportError, reportFileName), truncated(max), form-wizard's next, back, start, progress and step(index, count), and errors { required, email, phone, cui, iban, cnp, number, date, select, boolean, duplicate(row), tooLarge, unsupported, empty, parse, tooMany }. Counted strings are (count, formatted) => string.

• wizardClassNames
  FormWizardProps["classNames"]

  Classes for form-wizard's own parts (header, stepper, body, footer...).

• classNames
  Partial<Record<"upload" | "dropzone" | "template" | "file" | "sheet" | "header" | "map" | "mapRow" | "mapSample" | "review" | "reviewFilter" | "reviewTable" | "reviewCard" | "duplicates" | "skip" | "run" | "progress" | "summary" | "tile" | "report" | "footer", string>>

  Extra classes for the inner parts, each also marked with data-slot="csv-import-<part>".

• className
  string

  Classes for the wizard root (a form); other props spread onto it too.

Parts

FAQ

More React form components