# Import data

Take a spreadsheet in, match its columns to the product's fields and check the rows before anything lands.

For: Admins and operators bringing in records.

Web page: https://candor.themethodic.com/screens/import-data

## Layouts

### Drop, map, review

Pick it when: The default: a file arrives, columns are matched, rows are checked, then it lands.

Layout: A step bar across the top and the current step below it: the dropped file, the column mapping, the row check.

Items:

- **Data import** (`data-import`, Pro; https://candor.themethodic.com/docs/data-import.md): Drop a spreadsheet, then see what was read: rows, columns with sample values, and rows that couldn't be read.
- **Column mapper** (`column-mapper`, Pro; https://candor.themethodic.com/docs/column-mapper.md): Match file columns to the object's fields.
- **Import review** (`import-review`, Pro; https://candor.themethodic.com/docs/import-review.md): How many rows are ready, which need fixing and why, grouped by kind of problem.
- **Stepper** (`stepper`, Pro; https://candor.themethodic.com/docs/stepper.md): The steps of the import, with where the person is.
- **Reconcile table** (`reconcile-table`, Pro; https://candor.themethodic.com/docs/reconcile-table.md): Rows that would update records already there, matched against them: conflicts show both values, and the person resolves each.

```bash
npx candor-ui add data-import column-mapper import-review stepper reconcile-table
```

### Large file with progress

Pick it when: The file is big and the import takes time.

Layout: A measured progress bar with the rows done, and the problems found so far listed beneath.

Items:

- **Progress** (`progress`, free; https://candor.themethodic.com/docs/progress.md): A bar for work whose progress is measured: an upload, an import, an index.
- **Import review** (`import-review`, Pro; https://candor.themethodic.com/docs/import-review.md): Rows that need fixing, so far.
- **Task tray** (`task-tray`, Pro; https://candor.themethodic.com/docs/task-tray.md): Background work as one pill, so the person can leave the page.

```bash
npx candor-ui add progress import-review task-tray
```

## Rules that matter most here

- **Unknown stays unknown** (https://candor.themethodic.com/principles#unknown-stays-unknown): A cell that couldn't be read is shown as unread, with why; it isn't filled with a guess.
- **Say what can and can't be undone** (https://candor.themethodic.com/principles#say-what-can-be-undone): Importing says how many rows will be created or changed, and whether the import can be undone.
- **Nothing is pre-selected in a decision** (https://candor.themethodic.com/principles#nothing-preselected): A column the mapper isn't sure about starts unmapped.

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build a data import with Candor UI.
DataImport takes the file and shows what was read: rows, columns with sample values and rows that couldn't be read, with why.
ColumnMapper matches file columns to the object's fields. A column it can't match starts unmapped; don't preselect a guess.
ImportReview groups rows by kind of problem and says how many are ready.
Show Progress only where the figure is measured. For a long import, move it to a TaskTray pill.
Before the import lands, say how many rows are created or changed and whether it can be undone.

Start from the "Drop, map, review" layout: A step bar across the top and the current step below it: the dropped file, the column mapping, the row check.
Candor items: data-import (https://candor.themethodic.com/docs/data-import.md), column-mapper (https://candor.themethodic.com/docs/column-mapper.md), import-review (https://candor.themethodic.com/docs/import-review.md), stepper (https://candor.themethodic.com/docs/stepper.md), reconcile-table (https://candor.themethodic.com/docs/reconcile-table.md).
Install: npx candor-ui add data-import column-mapper import-review stepper reconcile-table
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```