All components (244)

Import data

Management · DataImportWizard

What it is and when to use it

A wizard to import data from a CSV or Excel (.xlsx) file in three steps: choosing the file, saying which column each field comes from and reviewing the converted rows before saving them.

When to use it

Loading customers, products or movements from a spreadsheet.
fields are the fields the application expects: each with its type (text, number, date, boolean), whether it is required (required), whether it cannot repeat (unique), other names the column may come with (aliases) and a rule of its own (validate).
It reads the file in the browser, without uploading it anywhere. It detects the separator, the encoding (UTF-8 or the one Excel uses in Spanish) and Excel dates. The Excel reader is loaded only when an .xlsx is chosen.
It matches the columns only by name; the second step lets you change them. Numbers and dates are read according to decimal and dateOrder, which the user can change in the first step.
onImport receives the correct rows, already converted. It can return how many went in and which ones the server rejected. Rows with errors are skipped, or prevent the import with allowPartial={false}.

When not to

Huge files: maxRows (10,000 by default) and maxSizeMb (10) limit what is read in the browser; for more, import on the server.
Old formats (.xls) or formulas that must be recalculated: from a formula it takes the last value Excel saved.
The validation here is of format. The server has to validate again.

Keyboard: they are normal controls; the wizard announces the new step and moves focus to it, and the preview is a region that scrolls with the arrows.

Accessibility: each column field has its label, errors are said with text in the cell as well as colour and the counts are announced.

Fine appearance: the preview highlights cells with problems in the error tone; the steps are those of Wizard.

What it looks like

File

File to import

Drag the file here

CSV, TSV or Excel (.xlsx). Up to 10 MB and 500 rows.

Upload a CSV or an .xlsx file to try it.

<DataImportWizard
  label="Import customers"
  fields={campos}
  maxRows={500}
  allowPartial
  onImport={(registros) => guardarClientes(registros)}
/>

Props

Import it with import { DataImportWizard } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`fields`required	`readonly ImportField[]`	The fields the application expects, with their type, whether they are required and their rules.
`label`required	`string`	What is imported («Import customers»): it names the wizard. Required.
`onImport`required	`(records: readonly ImportRecord[], context: ImportContext) => void \| ImportOutcome \| Promise<void \| ImportOutcome>`	Saves the valid rows. Without `batchSize` it is called once, with all of them; with it, once per batch. It can return how many went in and which ones the server rejected (`failed`), and they are counted in the result. If the first batch throws or rejects, the wizard says so and stays where it was; if a later one fails, it stops and the result says how many went in and how many are left. The library validates the format; the server has to validate again.
`allowPartial`	`boolean`	Import the correct rows even if there are others with errors. With `false`, a single error prevents the import. On by default.
`batchSize`	`number`	Sends the rows in batches of this size, one after another, with a progress bar and a button to cancel (the `context` signal fires to also cut the batch in progress). Without it, all at once.
`className`	`string`	Merged with the library classes; it does not replace them.
`dateOrder`	`DateOrder`	In `03/04/2026`, whether the day or the month comes first, at the start. The day by default.
`decimal`	`DecimalSeparator`	How decimals are written in the file, at the start. The comma by default.
`headingLevel`	`WizardHeadingLevel`	The level of each step's heading. 3 by default.
`maxRows`	`number`	How many rows the file can have at most. 10,000 by default.
`maxSizeMb`	`number`	The maximum size of the file, in megabytes. 10 by default.
`onDone`	`(outcome: ImportOutcome) => void`	Called when the import finishes, with what `onImport` returned.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: