Skip to content
Sheetwritev0.6.0

XLSX export

Download an active-sheet table or save a workbook with formulas and supported formatting.
On this page
Download the active table
import "@sheetwrite/xlsx/register";


await grid.exportXlsx("sales.xlsx");

For columns named Customer and Total with one row Ada, 120, the table file opens as:

AB
1CustomerTotal
2Ada120
sales.xlsx: synthesized headers, then data

Try it live: export the workbook.

Full setup

Install the optional package on the path that needs XLSX:

npm install @sheetwrite/xlsx

Use the workbook API to save an existing store without adding a header row:

Save all sheets and observe warnings
import { downloadBytes, toXlsxWorkbook } from "@sheetwrite/core";
import "@sheetwrite/xlsx/register";


const bytes = await toXlsxWorkbook(store.exportSnapshot(), {
  maxCells: 250_000,
  onWarning: (warning) => console.warn(warning.code, warning.message),
});
downloadBytes(bytes, "workbook.xlsx",
  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");

Table interchange

toXlsxTable(workbook, store, options?) returns Promise<Uint8Array>. grid.exportXlsx uses this contract: active sheet only, synthesized first-row column headers, and resolved scalars instead of formula source. Styles, borders, number/date formats, merges, column widths and row heights are preserved on active-sheet export. Frozen panes, active worksheet state and names are not table round-trip state.

Workbook interchange

toXlsxWorkbook(snapshot, options?) returns Promise<Uint8Array> from the same WorkbookSnapshot used by persistence. It does not synthesize a header row.

FeatureWorkbook result
Worksheets, order and active sheetPreserved.
Formula source, including cross-sheet formulasPreserved; requests full recalculation on open.
Styles, borders, number/date formats, merges, dimensions and frozen panesPreserved.
Named ranges and native booleansPreserved.
HTTPS/mailto and internal range hyperlinksPreserved, with stable IDs in Sheetwrite metadata.
Supported ordered conditional formatsNative rules preserve priority and stop behavior.
TablesAutofilter rules, sort state, calculated-column formulas and totals-row functions round-trip.
ValidationSheetwrite metadata preserved; supported list/numeric/date/text-length rules also emit native Excel validation.
Protected rangesMetadata preserved; no Excel sheet-protection claim is made.
Cell notesMetadata preserved and native Excel notes emitted.
Row groupsPreserved in metadata and emitted as native row outlines with hidden/collapsed state; native outline depth is capped at seven.
Rich textDisplay text preserved; structured warnings report flattening.
Unmodelled package partsKept under explicit edit rules, not automatically discarded.

Every dropped native feature is reported through onWarning (XlsxWorkbookWarning). Surface these warnings when fidelity matters. Import limits and conditional-rule support describe the supported subset.

Errors and built-in actions

grid.exportXlsx(...) rejects on missing registration or encoding failure and preserves the backend error. The four buffered table/workbook import/export functions are asynchronous. Missing registration and codec failures reject with SheetwriteError; inspect code, not the installation message. Resource failures remain XlsxResourceError instances and satisfy isSheetwriteError.

Built-in toolbar and context-menu actions show an alert and emit one export-error event with { format: "csv" | "xlsx", error }:

Observe built-in failures
grid.on("export-error", ({ format, error }) => {
  console.error(`${format} export failed`, error);
});

grid.actions.exportXlsx() returns a promise that resolves after the command finishes, including when export fails. Built-in buttons ignore repeated starts for the same pending command and show a busy state.

XLSX backends

Core and framework entry points do not resolve the optional codec. Register it before invoking XLSX functions or framework toolbar actions. A missing backend error names both remedies: install @sheetwrite/xlsx, then import @sheetwrite/xlsx/register.

The root @sheetwrite/xlsx entry is side-effect free. Its ./register entry registers idempotently. Explicit registration and individual backend composition are also public:

Explicit backend registration
import {
  registerXlsxBackends,
  sheetwriteTableExportBackend,
  sheetwriteTableImportBackend,
  sheetwriteWorkbookBackend,
} from "@sheetwrite/xlsx";
import {
  setXlsxTableExportBackend,
  setXlsxTableImportBackend,
  setXlsxWorkbookBackend,
} from "@sheetwrite/core";


registerXlsxBackends();
// Or register the roles individually when composing backends.
setXlsxTableExportBackend(sheetwriteTableExportBackend);
setXlsxTableImportBackend(sheetwriteTableImportBackend);
setXlsxWorkbookBackend(sheetwriteWorkbookBackend);

Hosts can implement XlsxWorkbookBackend, XlsxTableExportBackend, or XlsxTableImportBackend to replace a role. @sheetwrite/xlsx is the only concrete implementation package. Its bounded OOXML codec owns OPC part resolution, XML tokenization, styles and worksheet mapping over the audited compression primitive fflate.

Options and limits

All XLSX paths share XlsxWorkbookOptions: maxCells, resourceLimits, signal and onWarning. See resource limits and streaming before increasing a budget. Buffered export holds its output in memory.

See also

Documentation