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.
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 thanmaxCellsis 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 ismaxCellstimes 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:
defaultDelimitersets the delimiter and skips detection.defaultHeaderRowsets the header toggle. A number names the 0-based header row and drops the rows above it. See Control the import.valueModeis"formatted"(default) or"raw"."raw"reads an Excel cell as its stored value, without the number format.defaultSkipColumnsskips source columns by header text (any case) or 0-based index.mapColumn(header, index, { signal })returns a grid column id,nullto skip, orundefinedto keep the built-in match. It wins overdefaultSkipColumnsand can return a promise. A rejected promise falls back to the built-in match withdefaultSkipColumns. 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.
Related
- Control the import:
parseFile,csvEncoding,processImportRows,processCellFromText, andonImportError. - Import into a server grid: send the rows to your server.
- Import options: every field and limit.
- Export: the matching CSV and XLSX download.
- Validation: the
validatecheck that clears a cell on import.
Export
Download the rows of the grid as a CSV or XLSX file, or print them as a paged table, from a toolbar button or from code.
Export the whole result
Export every row of a server result, or of server pages or scroll mode, with a source function that returns the rows in batches, with limits and cancel.