gridcn2.0.0
Import and export

Import

Read a CSV or Excel file into grid rows with a dialog that maps the file's columns to grid columns and checks every cell.

Import reads a CSV, TSV, XLSX, or XLS file into rows. DataGridImportButton opens a dialog where the user picks a file, maps its columns, and checks a preview. The dialog runs every cell through the fromText of its column's cell type, as a paste does. It then appends the rows to the grid, or hands them to your onImport.

Export downloads the current view as a csv or xlsx file. Import accepts a csv or xlsx file (a sheet picker appears for multi-sheet workbooks), lets you map its columns, and appends the rows to the grid.

Name
Email
Role
Score
Silent Tiger
user0@example.com
Viewer
4
Quick Lion
user1@example.com
Viewer
89
Swift Wolf
user2@example.com
Manager
80
Eager Lion
user3@example.com
User
51
Eager Tiger
user4@example.com
Viewer
83
Silent Wolf
user5@example.com
User
15
Swift Lion
user6@example.com
Viewer
62
Eager Lion
user7@example.com
Manager
42
Eager Eagle
user8@example.com
Editor
35
Bold Tiger
user9@example.com
Editor
52
pnpm dlx shadcn@latest add @gridcn/data-grid-io

Import a file

Render this component inside the grid's provider. ./orders stands for your own module, and Order is your row type, here { id: string; customer: string; total: number }. The button appends the rows as one undoable change:

"use client";

import { DataGridImportButton } from "@/components/data-grid-io/data-grid-io";
import type { Order } from "./orders";

function createImportedRow(): Order {
  return { id: crypto.randomUUID(), customer: "", total: 0 };
}

export function ImportOrders() {
  return <DataGridImportButton createRow={createImportedRow} />;
}

createRow(index) builds the base row, with defaults for columns that the file lacks.

createRow can return a promise. A rejection imports nothing. Cancel stops a pending import.

Without onImport, a confirm appends the rows to data with one commitChange of the "import" source. That is one undo entry. The change reaches onDataChange, onSave, and validateRow like any other write. Replacing data does none of this. A grid with a totalRowCount or a readOnly grid has no default. Its import button is disabled, and its title gives the reason (labels.io.importNeedsOnImport or labels.io.importReadOnly). Pass onImport on a server grid.

onImport(rows) replaces the default and decides where the rows land: replace, merge, or send to a server. It can return a promise, which the dialog awaits. If it rejects, the dialog stays open with an error, and the user can retry. If it resolves, the dialog clears the grid selection. If the build cleared cells, it stays open (see Confirm). Otherwise it closes. On a readOnly grid, the dialog shows labels.io.importReadOnly and takes no import, also with onImport.

A commitChange runs the grid's validateRow for each inserted row, so imported rows show the same cross-field errors as edited rows. You need no extra validation call after the commit. See Cross-field rules.

Walk through the dialog

Choose a file

Drop a file on the zone or click it. After a file loads, a compact zone shows its name and replaces the file on a drop or click. The dialog takes .csv, .tsv, .xlsx, and .xls. The zone ignores a file whose name and type match none of these formats. A file over maxFileBytes shows the size message, whatever its type. A workbook opens on its first sheet, and a sheet picker switches sheets. A switch drops the column mapping that the user set by hand.

Header row

Clear the "first row is a header" toggle, which starts on, for a file without headers. The dialog then numbers the columns, keeps the mapping, and imports the first row as data.

Delimiter

A CSV or TSV file shows a delimiter menu with comma, semicolon, tab, and pipe. The dialog detects one of these four on load. A file with another separator reads as one column with a comma. If importDefaults sets one, the dialog uses it. A delimiter change drops the column mapping that the user set by hand. An Excel file has no delimiter menu.

Map columns

The dialog matches each header to a grid column by header text, then by column id. The match ignores case and the spaces around a header. A header without a match maps to "skip". Each grid column takes one source column at most. When two headers match one grid column, the first maps and the later one maps to "skip". The other menus disable a claimed column. A button next to each mapped menu skips it in one click.

Preview

The preview shows the first 10 rows with a note such as "Showing 10 of 250 rows".

Confirm

The dialog clears a cell that fails the validate of its column and keeps its row. A cell of a validationMode: "warn" column keeps its value and goes to flagged. The import still runs: the rows reach onImport, or the default append. The dialog then shows the count of cleared cells, disables Import, and stays open. A file over 5,000 data rows builds 2,000 rows at a time, and Cancel stops the build between batches.

Read Excel files

A file with an .xlsx or .xls name goes to the Excel reader. The reader then picks XLSX or XLS by the bytes of the file. Import options lists how each cell type comes in.

Import limits

The dialog rejects a file over a limit with a message and never cuts it. A NaN limit takes its default, and a negative limit counts as 0.

  • maxFileBytes: 50 MiB, checked before the read.
  • maxRows: 1,000,000. It counts the header row. maxColumns: 1,000.
  • maxCells: 5,000,000, rows times columns. A CSV file counts its widest row as its columns. The parser stops at the first row that breaks a limit. A CSV file with more delimiter characters than maxCells is rejected before the parse, even when quotes hide some of them.
  • maxDecompressedBytes: the unpacked size of one XLSX part, such as a worksheet or the shared strings. Without it, the cap is maxCells times 10 bytes plus 1 MiB, about 51 million bytes at the default. A value you set replaces that cap.

The shared strings of a workbook count as one part, so a text-heavy sheet with few cells can need a higher maxDecompressedBytes. A higher cap raises the memory that a read can use. An XLS file counts the cells of all its sheets against maxCells. An XLSX file counts the selected sheet only.

The dialog rejects an XLS file with more than maxCells / 2 + 100,000 records. The drop zone shows maxFileBytes.

Pass importLimits={{ maxRows: 10_000 }} to the button or the dialog to change a limit. parseImportFile takes the same fields.

Preset the dialog

importDefaults sets where the dialog starts, and the user can change every choice:

  • defaultDelimiter sets the delimiter and skips detection.
  • defaultHeaderRow sets the header toggle. A number names the 0-based header row and drops the rows above it. See Control the import.
  • valueMode is "formatted" (default) or "raw". "raw" reads an Excel cell as its stored value, without the number format.
  • defaultSkipColumns skips source columns by header text (any case) or 0-based index.
  • mapColumn(header, index, { signal }) returns a grid column id, null to skip, or undefined to keep the built-in match. It wins over defaultSkipColumns and can return a promise. A rejected promise falls back to the built-in match with defaultSkipColumns. When two answers name one grid column, the first keeps it and the later import column maps to "skip".

Import options lists every field.

Build your own import UI

useDataGridImportPreview() and the plain functions parseImportFile, matchImportColumns, applyImportOptions, and buildImportedRows build your own import UI. Import options lists their options and results.

Drop zone

The dialog's drop target is the dropzone item, which data-grid-io installs. Use Dropzone alone for any file drop. Import options lists its props.

Server mode

Import reads no sort, filter, page, or server state. A grid with a totalRowCount cannot take appended rows, so it needs onImport. Without onImport, the import button is disabled. Send the rows to your API there, and call server.refresh(). See Import into a server grid.

On this page