gridcn2.0.0
Import and export

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.

A grid with server pages or scroll mode holds only part of its result. Pass a source to exportGrid or to DataGridExportButton to write all of it. This page applies to server pages and to scroll mode.

Loading…. Filter or search, then use the download menu: the plain items export this page, "Export all rows" exports the whole result. Import adds the file's rows on the server.

Name
Email
Score
Page 1

Before you start

  • Install data-grid-io. See Export.
  • Pick an endpoint that returns rows for the grid's spec: the sort, the filters, and the search text. Your server applies the spec. The grid applies nothing to the rows.

Steps

  1. Write the source. It returns an array, or an async iterable of row batches. It receives { spec, signal, columnIds }.
  2. Pass it in options. Set maxRows to the most rows your server can send.

This source pages through your API 500 rows at a time:

import {
  DataGridExportButton,
  type ExportSourceContext,
} from "@/components/data-grid-io/data-grid-io";
import { api, type Order } from "./api";

async function* ordersSource({ spec, signal, columnIds }: ExportSourceContext) {
  for (let offset = 0; ; offset += 500) {
    const query = { ...spec, offset, limit: 500, columns: columnIds };
    const rows: Order[] = await api.orders(query, { signal });
    if (rows.length === 0) return;
    yield rows;
  }
}

export function ExportAll() {
  const options = { source: ordersSource, maxRows: 200_000 };
  return <DataGridExportButton options={options} />;
}

Result

With a source, DataGridExportButton adds "Export all rows" items. The plain items still export the rows the grid holds. While an all-rows export runs, the menu shows "Cancel export". When the export ends, the button announces the row count. It says so when a limit made the file incomplete.

A client grid with defaultPageSize holds every row, so its plain items cover all pages already. For server pages, pass a source that fetches every page from your API. The source returns the rows in the order you choose.

exportGrid resolves { rowCount, truncated }. truncated is true when maxRows or maxBytes left rows of the source out. The file then holds the rows read so far.

Limits and options

OptionDefaultMeaning
sourcenoneWhere the rows of the whole result come from. scope does not apply.
maxRows1,000,000Stops the export after this many data rows. An xlsx file also stops at the Excel sheet limit and at 5,000,000 cells.
maxBytes256 MiBStops at the first 1,000-row slice that passes this much file text. The header row and the byte order mark are not counted. An xlsx file counts characters.
signalnoneCancels the export. The promise rejects and no file downloads.
onProgressnoneCalled after each batch with { rowCount, byteCount }.
  • Each batch must be an array. Any other value rejects the export and downloads nothing.
  • The export skips null and undefined rows.
  • A source that returns more than 1,000 empty batches in a row rejects. So does a source that returns more than twice maxRows (at least 2) null or undefined rows over the whole export. A source that reaches maxRows first ends the export instead.
  • A source that returns more rows than maxRows is cut at maxRows.
  • A maxRows or maxBytes below 0 counts as 0.
  • A CSV cell that looks like a formula gets the same quote prefix as in a loaded export.
  • A CSV or xlsx export holds the rows in memory until the source ends. The browser then builds one file and downloads it. Memory grows with the file size.
  • Set maxRows and maxBytes to what the memory of your users' devices can hold. The defaults stop at 1,000,000 rows or 256 MiB of file text, whichever comes first. To export more, raise both together: 2,000,000 rows of 150 bytes make about 300 MB, which is above the default maxBytes.
  • For a result larger than a browser holds, export on the server and link to the file.
  • An xlsx export with an invalid sheetName rejects before the source runs.

On this page