CSV Column Mapper

ProNew

A three-step CSV import: choose a file, map its columns to your fields (matched automatically by name), review the first rows and the rows that failed validation, then import. Includes a quote-aware CSV parser.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/csv-column-mapper

Usage

Everything runs in the browser: the file is read with File.text() and parsed locally, and onImport receives clean rows keyed by your field keys. For very large files, parse in a worker or send the file to the server and use this only for the mapping step (parseCsv, autoMap are exported).

Exports

Export	Description
`CsvColumnMapper`	The three-step flow.
`parseCsv(text, delimiter?)`	A quote-aware CSV parser, returns `string[][]`.
`autoMap(headers, fields)`	The automatic column match, as `{ fieldKey: columnIndex \| null }`.
`detectDelimiter(text)`	`,`, `;` or tab.

Props

Prop	Type	Default	Description
`fields`	`{ key, label, required?, aliases? }[]`	-	What you want to import.
`validateRow`	`(row) => string \| null`	-	A message flags the row; flagged rows are skipped.
`onImport`	`(rows, { skipped, fileName }) => void \| Promise<void>`	-	Gets the valid rows. A throw shows the message and stays on Review.
`maxRows`	`number`	`10000`	Data rows allowed.

Accessibility

The steps are an ordered list; the current one has aria-current="step". When the step changes, focus moves to its heading so keyboard and screen reader users start at the new content.
The file chooser is a native file input inside a label (visually hidden, focus ring on the label). Each field mapping is a labelled native select, aria-invalid while a required field is unmatched; the list of what is missing is a status message.
The review table is a real table; rows to be skipped are listed in a disclosure with line numbers and reasons, and the counts are announced as status text.
Errors (empty file, too many rows, a failed import) use role="alert".

Testing

The component ships with a Testing Library test (csv-column-mapper.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/csv-column-mapper

Usage

Exports

Export	Description
`CsvColumnMapper`	The three-step flow.
`parseCsv(text, delimiter?)`	A quote-aware CSV parser, returns `string[][]`.
`autoMap(headers, fields)`	The automatic column match, as `{ fieldKey: columnIndex \| null }`.
`detectDelimiter(text)`	`,`, `;` or tab.

Props

Prop	Type	Default	Description
`fields`	`{ key, label, required?, aliases? }[]`	-	What you want to import.
`validateRow`	`(row) => string \| null`	-	A message flags the row; flagged rows are skipped.
`onImport`	`(rows, { skipped, fileName }) => void \| Promise<void>`	-	Gets the valid rows. A throw shows the message and stays on Review.
`maxRows`	`number`	`10000`	Data rows allowed.

Accessibility

The steps are an ordered list; the current one has aria-current="step". When the step changes, focus moves to its heading so keyboard and screen reader users start at the new content.
The file chooser is a native file input inside a label (visually hidden, focus ring on the label). Each field mapping is a labelled native select, aria-invalid while a required field is unmatched; the list of what is missing is a status message.
The review table is a real table; rows to be skipped are listed in a disclosure with line numbers and reasons, and the counts are announced as status text.
Errors (empty file, too many rows, a failed import) use role="alert".

Testing

The component ships with a Testing Library test (csv-column-mapper.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.