Data operations and export

Installation

Sheetwrite can sort, filter, hide, group, aggregate, import, and export the active sheet without rewriting the stored row data. Sorts and filters are display views: the store keeps a row-order permutation/subset and the renderer reads through it.

Display views

The simple shorthands are still available:

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.sortByGrid.sortBy(col: number, ascending?: boolean): voidGrid.sortBy(col: number, ascending?: boolean): voidGrid.sortBy(col: number, ascending?: boolean): voidSort the displayed rows by a column (does not mutate stored data).API reference →(4);            // sort by column 4, ascending
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.sortByGrid.sortBy(col: number, ascending?: boolean): voidGrid.sortBy(col: number, ascending?: boolean): voidGrid.sortBy(col: number, ascending?: boolean): voidSort the displayed rows by a column (does not mutate stored data).API reference →(4, false);     // descending
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.filterByGrid.filterBy(col: number, needle: string): voidGrid.filterBy(col: number, needle: string): voidGrid.filterBy(col: number, needle: string): voidFilter the displayed rows to those whose column text contains needle.API reference →(3, "Tokyo"); // keep rows whose column-3 text contains "Tokyo"
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.clearViewGrid.clearView(): voidGrid.clearView(): voidGrid.clearView(): voidClear any active sort/filter view.API reference →();          // clear sort/filter state only

For custom UI, use the composable primitives. All active column filters are ANDed together, hidden rows and collapsed groups are subtracted, and the remaining rows are sorted by the active multi-key sort.

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.sortByMultiGrid.sortByMulti(keys: readonly SortKey[]): voidGrid.sortByMulti(keys: readonly SortKey[]): voidGrid.sortByMulti(keys: readonly SortKey[]): voidMulti-key sort of the displayed rows (first key primary; stable).API reference →([
  { colSortKey.col: numberinterface SortKey {
  col: number;
}interface SortKey {
  col: number;
}: 4, ascendingSortKey.ascending: booleaninterface SortKey {
  ascending: boolean;
}interface SortKey {
  ascending: boolean;
}: false }, // primary key
  { colSortKey.col: numberinterface SortKey {
  col: number;
}interface SortKey {
  col: number;
}: 0, ascendingSortKey.ascending: booleaninterface SortKey {
  ascending: boolean;
}interface SortKey {
  ascending: boolean;
}: true },  // tie-breaker
]);

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.setColumnFilterGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidSet or clear (null) one column's filter. All column filters AND together and compose with the active sort and hidden rows.API reference →(3, { kind: "contains", texttext: stringlet text: stringlet text: stringFormula source when the cell is a formula, else the literal display text.API reference →: "Tokyo" });
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.setColumnFilterGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidSet or clear (null) one column's filter. All column filters AND together and compose with the active sort and hidden rows.API reference →(2, { kind: "values", valuesvalues: readonly CellScalar[]let values: readonly CellScalar[]let values: readonly CellScalar[]row-major resolved values, length (end-start) * cols.lengthAPI reference →: ["Retail", "Partner"] });
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.setColumnFilterGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidSet or clear (null) one column's filter. All column filters AND together and compose with the active sort and hidden rows.API reference →(5, { kind: "compare", opop: "gt" | "gte" | "lt" | "lte" | "eq" | "neq"let op: "gt" | "gte" | "lt" | "lte" | "eq" | "neq"let op:
  | "gt"
  | "gte"
  | "lt"
  | "lte"
  | "eq"
  | "neq": "gte", valuevalue: numberlet value: numberlet value: number: 1000 });

const citiesconst cities: CellScalar[]const cities: CellScalar[]const cities: CellScalar[] = gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.distinctValuesGrid.distinctValues(col: number, limit?: number): CellScalar[]Grid.distinctValues(col: number, limit?: number): CellScalar[]Grid.distinctValues(col: number, limit?: number): CellScalar[]Distinct resolved values of a column (Rust scan), capped at limit (default 1000) — the data source for a filter-by-values UI.API reference →(3, 100); // data source for a filter menu

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.hideRowsGrid.hideRows(rows: readonly number[]): voidGrid.hideRows(rows: readonly number[]): voidGrid.hideRows(rows: readonly number[]): voidHide the given data rows (composes with filters/sort).API reference →([1, 7, 9]);
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.groupRowsGrid.groupRows(start: number, end: number): voidGrid.groupRows(start: number, end: number): voidGrid.groupRows(start: number, end: number): voidDefine a collapsible row group over a data-row range (end-inclusive).API reference →(10, 25);
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.setGroupCollapsedGrid.setGroupCollapsed(start: number, collapsed: boolean): voidGrid.setGroupCollapsed(start: number, collapsed: boolean): voidGrid.setGroupCollapsed(start: number, collapsed: boolean): voidCollapse/expand a row group; collapsing hides its rows.API reference →(10, true);

Method	Signature	Effect
`sortBy`	`sortBy(col: number, ascending = true): void`	Reorder displayed rows by one column.
`sortByMulti`	`sortByMulti(keys: readonly SortKey[]): void`	Stable multi-key sort; first key is primary.
`filterBy`	`filterBy(col: number, needle: string): void`	Shorthand for a case-insensitive `contains` column filter.
`setColumnFilter`	`setColumnFilter(col: number, filter: ColumnFilter \| null): void`	Set or clear one column filter.
`getColumnFilters`	`getColumnFilters(): ReadonlyMap<number, ColumnFilter>`	Current active column filters.
`distinctValues`	`distinctValues(col: number, limit = 1000): CellScalar[]`	First-seen distinct resolved values for a column.
`hideRows` / `showRows`	`hideRows(rows)` / `showRows(rows?)`	Hide/show data rows independent of sort/filter state.
`hiddenRows`	`hiddenRows(): readonly number[]`	Currently hidden data rows.
`groupRows` / `ungroupRows`	`groupRows(start, end)` / `ungroupRows(start, end)`	Create/remove an inclusive data-row group.
`setGroupCollapsed`	`setGroupCollapsed(start, collapsed): void`	Collapse or expand the group starting at `start`.
`rowGroups`	`rowGroups(): readonly RowGroup[]`	Current row-group definitions.
`clearView`	`clearView(): void`	Clears sort/filter state. Hidden rows and row groups are preserved.

clearView() deliberately does not unhide rows or expand row groups. This matches spreadsheet behavior: clearing a filter removes the query, but explicit hidden rows and collapsed groups remain a separate visibility state. Use showRows() and setGroupCollapsed(start, false) to reverse those states.

Because a view reorders or hides rows, two features that depend on a stable row-to-cell mapping are disabled while a view is active:

Merged cells are not drawn (the layout reports no merges under a view).
Drag-to-fill is unavailable (the fill handle is hidden).

Call clearView() to remove sort/filter state; also show hidden rows / expand row groups if you need the full natural data order.

Aggregate

aggregate computes a column reduction over the active sheet's data and returns a number:

type Aggregatetype Aggregate = (col: number, op: AggregateOp) => numbertype Aggregate = (col: number, op: AggregateOp) => number;type Aggregate = (
  col: number,
  op: AggregateOp,
) => number; = Gridinterface Gridinterface Gridinterface GridImperative grid handle for document commands, events, rendering, and teardown.API reference →["aggregate"];

const totalconst total: numberconst total: numberconst total: number = gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.aggregateGrid.aggregate(col: number, op: AggregateOp): numberGrid.aggregate(col: number, op: AggregateOp): numberGrid.aggregate(col: number, op: AggregateOp): numberColumn aggregate over the active sheet's data.API reference →(4, "sum");
const rowsconst rows: numberconst rows: numberconst rows: numberend-exclusive row rangeAPI reference → = gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.aggregateGrid.aggregate(col: number, op: AggregateOp): numberGrid.aggregate(col: number, op: AggregateOp): numberGrid.aggregate(col: number, op: AggregateOp): numberColumn aggregate over the active sheet's data.API reference →(0, "count");

Frozen panes and zoom

Frozen panes and zoom are view geometry, not data mutations:

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.setFrozenGrid.setFrozen(rows: number, cols?: number): voidGrid.setFrozen(rows: number, cols?: number): voidGrid.setFrozen(rows: number, cols?: number): voidPin the first rows view rows and cols columns; they stay visible while the body scrolls (0 = unfreeze that axis). Persisted on the active sheet.API reference →(1, 1); // pin first view row and first column
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.setFrozenGrid.setFrozen(rows: number, cols?: number): voidGrid.setFrozen(rows: number, cols?: number): voidGrid.setFrozen(rows: number, cols?: number): voidPin the first rows view rows and cols columns; they stay visible while the body scrolls (0 = unfreeze that axis). Persisted on the active sheet.API reference →(0, 0); // unfreeze

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.setZoomGrid.setZoom(zoom: number): voidGrid.setZoom(zoom: number): voidGrid.setZoom(zoom: number): voidContent zoom factor (0.5–2): scales row/column geometry and fonts.API reference →(1.25);
consolevar console: Consolevar console: Consolevar console: Console.logConsole.log(...data: any[]): void (+1 overload)Console.log(...data: any[]): void (+1 overload)Console.log(...data: any[]): void (+1 overload)The console.log() static method outputs a message to the console. MDN Reference(gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.getZoomGrid.getZoom(): numberGrid.getZoom(): numberGrid.getZoom(): number());

setFrozen(rows, cols?) pins leading view rows and columns while the body scrolls. setZoom(z) clamps to 0.5-2 and scales painted row/column geometry and fonts; workbook widths/heights remain in base units.

Export

The grid can download the active sheet directly. CSV is synchronous; XLSX is async because the optional backend produces bytes asynchronously. Install and register @sheetwrite/xlsx before enabling a framework toolbar export action or calling grid.exportXlsx:

npm install @sheetwrite/xlsx

import "@sheetwrite/xlsx/register";

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.exportCsvGrid.exportCsv(filename: string): voidGrid.exportCsv(filename: string): voidGrid.exportCsv(filename: string): void("sales.csv");
await gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.exportXlsxGrid.exportXlsx(filename: string): Promise<void>Grid.exportXlsx(filename: string): Promise<void>Grid.exportXlsx(filename: string): Promise<void>("sales.xlsx");

grid.exportXlsx(...) rejects when registration or encoding fails, preserving the backend error. Built-in toolbar and context-menu actions cannot return that promise, so the grid emits one export-error event with { format: "xlsx", error } instead:

gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.onGrid.on<"export-error">(evt: "export-error", fn: (e: {
    format: "xlsx";
    error: unknown;
}) => void): () => voidGrid.on<"export-error">(evt: "export-error", fn: (e: {
    format: "xlsx";
    error: unknown;
}) => void): () => voidGrid.on<"export-error">(evt: "export-error", fn: (e: {
    format: "xlsx";
    error: unknown;
}) => void): () => void("export-error", ({ formatformat: "xlsx"let format: "xlsx"let format: "xlsx"Column input format, for parseCellInput.API reference →, errorerror: unknownlet error: unknownlet error: unknown }) => {
  consolevar console: Consolevar console: Consolevar console: Console.errorConsole.error(...data: any[]): void (+1 overload)Console.error(...data: any[]): void (+1 overload)Console.error(...data: any[]): void (+1 overload)Log to stderr in your terminal Appears in red@param data something to display(`${formatformat: "xlsx"let format: "xlsx"let format: "xlsx"Column input format, for parseCellInput.API reference →} export failed`, errorerror: unknownlet error: unknownlet error: unknown);
});

CSV is written UTF-8 with a BOM and CRLF line endings, and string values are injection-hardened — a value starting with =, +, -, @, tab, or CR is prefixed with a single quote so it cannot become an executable formula when reopened in a spreadsheet app.

Clipboard formulas and references retain their rich behavior only for a copy/cut pasted back through the same live Sheetwrite grid controller. Rich payloads from another controller or application, including spreadsheet HTML, paste as injection-neutralized text; pasteValues uses resolved literals.

Standalone import/export functions

Sheetwrite exposes two intentionally different XLSX contracts:

Table interchange: toXlsxTable / fromXlsxTable. This is the active-sheet, first-row-header API used by grid.exportXlsx.
Workbook round-trip: toXlsxWorkbook / fromXlsxWorkbook. This consumes and produces the same WorkbookSnapshot used by persistence, without adding a header row.

import {
  downloadBytesfunction downloadBytes(bytes: Uint8Array | string, filename: string, mime: string): voidfunction downloadBytes(
  bytes: Uint8Array | string,
  filename: string,
  mime: string,
): voidfunction downloadBytes(
  bytes: Uint8Array | string,
  filename: string,
  mime: string,
): voidTrigger a browser download from in-memory bytes. The temporary anchor is removed and its object URL is scheduled for revocation even when DOM append or click throws.API reference →,
  fromCsvfunction fromCsv(text: string, columns: readonly Column[], options?: DelimitedTextOptions): ColumnarDatafunction fromCsv(
  text: string,
  columns: readonly Column[],
  options?: DelimitedTextOptions,
): ColumnarDatafunction fromCsv(
  text: string,
  columns: readonly Column[],
  options?: DelimitedTextOptions,
): ColumnarDataParse CSV into ColumnarData. The first record is consumed as a positional header. Input fields project onto declared visible columns; hidden declared columns are initialized to null, matching the visible-column CSV export. Extra fields are ignored and missing fields become null. The returned columnar table is fully materialized in memory.API reference →,
  fromXlsxTablefunction fromXlsxTable(data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions): Promise<ColumnarData>function fromXlsxTable(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<ColumnarData>function fromXlsxTable(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<ColumnarData>Parse the first sheet of .xlsx bytes into ColumnarData. The first parsed row is treated as the header and its cell text becomes each column's key. Numbers stay numbers, date cells use the date-serial convention, strings are verbatim, and empty cells become null.API reference →,
  fromXlsxWorkbookfunction fromXlsxWorkbook(data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions): Promise<WorkbookSnapshot>function fromXlsxWorkbook(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<WorkbookSnapshot>function fromXlsxWorkbook(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<WorkbookSnapshot>Formula-preserving, multi-sheet workbook import through the optional XLSX backend.API reference →,
  SheetwriteStoreclass SheetwriteStoreclass SheetwriteStoreclass SheetwriteStoreStable public facade and the sole transaction, epoch, policy, and event barrier.API reference →,
  toCsvfunction toCsv(sheet: Sheet, store: Store, options?: DelimitedTextOptions): stringfunction toCsv(
  sheet: Sheet,
  store: Store,
  options?: DelimitedTextOptions,
): stringfunction toCsv(
  sheet: Sheet,
  store: Store,
  options?: DelimitedTextOptions,
): stringExport the current visible CSV view (UTF-8 BOM, CRLF): visible columns and view-ordered rows surviving sort, filter, hidden-row, and group state. String values beginning with = + - @ \t \r are prefixed with '. The synchronous API returns one in-memory string, but fetches at most maxWriterWindowRows view rows from the store per read.@throws {@link IncompleteDataError} before serialization when a paged sheet is incomplete.@throws {@link DelimitedTextResourceError} when a configured resource ceiling is exceeded.API reference →,
  toTsvfunction toTsv(range: Range, store: Store, options?: DelimitedTextOptions): stringfunction toTsv(
  range: Range,
  store: Store,
  options?: DelimitedTextOptions,
): stringfunction toTsv(
  range: Range,
  store: Store,
  options?: DelimitedTextOptions,
): stringExport a canonical data-space range as clipboard-compatible TSV (CRLF, no BOM). Reversed corners are normalized; active sort and filter views do not remap the supplied row coordinates. Values are injection-hardened. The synchronous API returns one in-memory string and fetches at most maxWriterWindowRows canonical rows per packed store read.@throws {@link IncompleteDataError} before serialization when a paged sheet is incomplete.@throws {@link DelimitedTextResourceError} when a configured resource ceiling is exceeded.API reference →,
  toXlsxTablefunction toXlsxTable(workbook: Workbook, store: Store, options?: XlsxWorkbookOptions): Promise<Uint8Array>function toXlsxTable(
  workbook: Workbook,
  store: Store,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>function toXlsxTable(
  workbook: Workbook,
  store: Store,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>Exports a table model through the registered optional XLSX backend.API reference →,
  toXlsxWorkbookfunction toXlsxWorkbook(input: WorkbookSnapshot | Pick<Grid, "exportSnapshot">, options?: XlsxWorkbookOptions): Promise<Uint8Array>function toXlsxWorkbook(
  input: WorkbookSnapshot | Pick<Grid, "exportSnapshot">,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>function toXlsxWorkbook(
  input:
    | WorkbookSnapshot
    | Pick<
        Grid,
        "exportSnapshot"
      >,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>Formula-preserving, multi-sheet workbook export through the optional XLSX backend.API reference →,
} from "@sheetwrite/core";
import "@sheetwrite/xlsx/register";

const dataFromCsvconst dataFromCsv: ColumnarDataconst dataFromCsv: ColumnarDataconst dataFromCsv: ColumnarData = fromCsvfunction fromCsv(text: string, columns: readonly Column[], options?: DelimitedTextOptions): ColumnarDatafunction fromCsv(
  text: string,
  columns: readonly Column[],
  options?: DelimitedTextOptions,
): ColumnarDatafunction fromCsv(
  text: string,
  columns: readonly Column[],
  options?: DelimitedTextOptions,
): ColumnarDataParse CSV into ColumnarData. The first record is consumed as a positional header. Input fields project onto declared visible columns; hidden declared columns are initialized to null, matching the visible-column CSV export. Extra fields are ignored and missing fields become null. The returned columnar table is fully materialized in memory.API reference →(csvTextconst csvText: stringconst csvText: stringconst csvText: string, columnsconst columns: readonly SimpleColumn<Record<string, CellScalar>>[]const columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]const columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]Restrict to these column indices (defaults to all columns).API reference →);
const tableBytesconst tableBytes: Uint8Array<ArrayBufferLike>const tableBytes: Uint8Array<ArrayBufferLike>const tableBytes: Uint8Array<ArrayBufferLike> = await toXlsxTablefunction toXlsxTable(workbook: Workbook, store: Store, options?: XlsxWorkbookOptions): Promise<Uint8Array>function toXlsxTable(
  workbook: Workbook,
  store: Store,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>function toXlsxTable(
  workbook: Workbook,
  store: Store,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>Exports a table model through the registered optional XLSX backend.API reference →(workbookconst workbook: Workbookconst workbook: Workbookconst workbook: WorkbookLive workbook schema adopted by the store and updated by document operations.API reference →, storeconst store: Storeconst store: Storeconst store: Store);
const dataFromTableconst dataFromTable: ColumnarDataconst dataFromTable: ColumnarDataconst dataFromTable: ColumnarData = await fromXlsxTablefunction fromXlsxTable(data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions): Promise<ColumnarData>function fromXlsxTable(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<ColumnarData>function fromXlsxTable(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<ColumnarData>Parse the first sheet of .xlsx bytes into ColumnarData. The first parsed row is treated as the header and its cell text becomes each column's key. Numbers stay numbers, date cells use the date-serial convention, strings are verbatim, and empty cells become null.API reference →(tableBytesconst tableBytes: Uint8Array<ArrayBufferLike>const tableBytes: Uint8Array<ArrayBufferLike>const tableBytes: Uint8Array<ArrayBufferLike>);

const workbookBytesconst workbookBytes: Uint8Array<ArrayBufferLike>const workbookBytes: Uint8Array<ArrayBufferLike>const workbookBytes: Uint8Array<ArrayBufferLike> = await toXlsxWorkbookfunction toXlsxWorkbook(input: WorkbookSnapshot | Pick<Grid, "exportSnapshot">, options?: XlsxWorkbookOptions): Promise<Uint8Array>function toXlsxWorkbook(
  input: WorkbookSnapshot | Pick<Grid, "exportSnapshot">,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>function toXlsxWorkbook(
  input:
    | WorkbookSnapshot
    | Pick<
        Grid,
        "exportSnapshot"
      >,
  options?: XlsxWorkbookOptions,
): Promise<Uint8Array>Formula-preserving, multi-sheet workbook export through the optional XLSX backend.API reference →(storeconst store: Storeconst store: Storeconst store: Store.exportSnapshotStore.exportSnapshot?(): WorkbookSnapshotStore.exportSnapshot?(): WorkbookSnapshotStore.exportSnapshot?(): WorkbookSnapshotDeterministic, JSON-safe authoritative runtime document.API reference →(), {
  maxCellsXlsxWorkbookOptions.maxCells?: number | undefinedinterface XlsxWorkbookOptions {
  maxCells?: number | undefined;
}interface XlsxWorkbookOptions {
  maxCells?: number | undefined;
}Maximum logical cells processed. Defaults to 1,000,000.API reference →: 250_000,
  signalXlsxWorkbookOptions.signal?: AbortSignal | undefinedinterface XlsxWorkbookOptions {
  signal?: AbortSignal | undefined;
}interface XlsxWorkbookOptions {
  signal?:
    AbortSignal | undefined;
}Abort before or between bounded codec operations.API reference →: abortControllerconst abortController: AbortControllerconst abortController: AbortControllerconst abortController: AbortController.signalAbortController.signal: AbortSignalinterface AbortController {
  signal: AbortSignal;
}interface AbortController {
  signal: AbortSignal;
}The signal read-only property of the AbortController interface returns an AbortSignal object instance, which can be used to communicate with/abort an asynchronous operation as desired. MDN ReferenceAPI reference →,
  onWarningXlsxWorkbookOptions.onWarning?: ((warning: XlsxWorkbookWarning) => void) | undefinedinterface XlsxWorkbookOptions {
  onWarning?: ((warning: XlsxWorkbookWarning) => void) | undefined;
}interface XlsxWorkbookOptions {
  onWarning?:
    | ((
        warning: XlsxWorkbookWarning,
      ) => void)
    | undefined;
}: (warningwarning: XlsxWorkbookWarninglet warning: XlsxWorkbookWarninglet warning: XlsxWorkbookWarning) => consolevar console: Consolevar console: Consolevar console: Console.warnConsole.warn(...data: any[]): void (+1 overload)Console.warn(...data: any[]): void (+1 overload)Console.warn(...data: any[]): void (+1 overload)The console.warn() static method outputs a warning message to the console at the 'warning' log level. MDN Reference(warningwarning: XlsxWorkbookWarninglet warning: XlsxWorkbookWarninglet warning: XlsxWorkbookWarning.codeXlsxWorkbookWarning.code: "boolean-literal" | "rich-text" | "hyperlink" | "unsupported-cell-value" | "unsupported-feature" | "external-relationship" | "external-formula" | "format-loss" | "validation-loss" | "invalid-metadata"interface XlsxWorkbookWarning {
  code:
    | "boolean-literal"
    | "rich-text"
    | "hyperlink"
    | "unsupported-cell-value"
    | "unsupported-feature"
    | "external-relationship"
    | "external-formula"
    | "format-loss"
    | "validation-loss"
    | "invalid-metadata";
}interface XlsxWorkbookWarning {
  code:
    | "boolean-literal"
    | "rich-text"
    | "hyperlink"
    | "unsupported-cell-value"
    | "unsupported-feature"
    | "external-relationship"
    | "external-formula"
    | "format-loss"
    | "validation-loss"
    | "invalid-metadata";
}, warningwarning: XlsxWorkbookWarninglet warning: XlsxWorkbookWarninglet warning: XlsxWorkbookWarning.messageXlsxWorkbookWarning.message: stringinterface XlsxWorkbookWarning {
  message: string;
}interface XlsxWorkbookWarning {
  message: string;
}),
});
const importedSnapshotconst importedSnapshot: WorkbookSnapshotconst importedSnapshot: WorkbookSnapshotconst importedSnapshot: WorkbookSnapshot = await fromXlsxWorkbookfunction fromXlsxWorkbook(data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions): Promise<WorkbookSnapshot>function fromXlsxWorkbook(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<WorkbookSnapshot>function fromXlsxWorkbook(
  data: ArrayBuffer | Uint8Array,
  options?: XlsxWorkbookOptions,
): Promise<WorkbookSnapshot>Formula-preserving, multi-sheet workbook import through the optional XLSX backend.API reference →(workbookBytesconst workbookBytes: Uint8Array<ArrayBufferLike>const workbookBytes: Uint8Array<ArrayBufferLike>const workbookBytes: Uint8Array<ArrayBufferLike>);
const importedStoreconst importedStore: SheetwriteStoreconst importedStore: SheetwriteStoreconst importedStore: SheetwriteStore = SheetwriteStoreclass SheetwriteStoreclass SheetwriteStoreclass SheetwriteStoreStable public facade and the sole transaction, epoch, policy, and event barrier.API reference →.fromSnapshotSheetwriteStore.fromSnapshot(input: unknown, options?: SheetwriteStoreOptions): SheetwriteStoreSheetwriteStore.fromSnapshot(input: unknown, options?: SheetwriteStoreOptions): SheetwriteStoreSheetwriteStore.fromSnapshot(input: unknown, options?: SheetwriteStoreOptions): SheetwriteStore(importedSnapshotconst importedSnapshot: WorkbookSnapshotconst importedSnapshot: WorkbookSnapshotconst importedSnapshot: WorkbookSnapshot);

const csvconst csv: stringconst csv: stringconst csv: string = toCsvfunction toCsv(sheet: Sheet, store: Store, options?: DelimitedTextOptions): stringfunction toCsv(
  sheet: Sheet,
  store: Store,
  options?: DelimitedTextOptions,
): stringfunction toCsv(
  sheet: Sheet,
  store: Store,
  options?: DelimitedTextOptions,
): stringExport the current visible CSV view (UTF-8 BOM, CRLF): visible columns and view-ordered rows surviving sort, filter, hidden-row, and group state. String values beginning with = + - @ \t \r are prefixed with '. The synchronous API returns one in-memory string, but fetches at most maxWriterWindowRows view rows from the store per read.@throws {@link IncompleteDataError} before serialization when a paged sheet is incomplete.@throws {@link DelimitedTextResourceError} when a configured resource ceiling is exceeded.API reference →(sheetconst sheet: stringconst sheet: stringconst sheet: stringRestrict to a sheet (defaults to the active sheet).API reference →, storeconst store: Storeconst store: Storeconst store: Store); // string (BOM + CRLF, injection-hardened)
const tsvconst tsv: stringconst tsv: stringconst tsv: string = toTsvfunction toTsv(range: Range, store: Store, options?: DelimitedTextOptions): stringfunction toTsv(
  range: Range,
  store: Store,
  options?: DelimitedTextOptions,
): stringfunction toTsv(
  range: Range,
  store: Store,
  options?: DelimitedTextOptions,
): stringExport a canonical data-space range as clipboard-compatible TSV (CRLF, no BOM). Reversed corners are normalized; active sort and filter views do not remap the supplied row coordinates. Values are injection-hardened. The synchronous API returns one in-memory string and fetches at most maxWriterWindowRows canonical rows per packed store read.@throws {@link IncompleteDataError} before serialization when a paged sheet is incomplete.@throws {@link DelimitedTextResourceError} when a configured resource ceiling is exceeded.API reference →(rangeconst range: {
    start: CellAddress;
    end: CellAddress;
}const range: {
  start: CellAddress;
  end: CellAddress;
}const range: {
  start: CellAddress;
  end: CellAddress;
}, storeconst store: Storeconst store: Storeconst store: Store); // string (Excel/Sheets clipboard TSV)

downloadBytesfunction downloadBytes(bytes: Uint8Array | string, filename: string, mime: string): voidfunction downloadBytes(
  bytes: Uint8Array | string,
  filename: string,
  mime: string,
): voidfunction downloadBytes(
  bytes: Uint8Array | string,
  filename: string,
  mime: string,
): voidTrigger a browser download from in-memory bytes. The temporary anchor is removed and its object URL is scheduled for revocation even when DOM append or click throws.API reference →(csvconst csv: stringconst csv: stringconst csv: string, "sales.csv", "text/csv");
downloadBytesfunction downloadBytes(bytes: Uint8Array | string, filename: string, mime: string): voidfunction downloadBytes(
  bytes: Uint8Array | string,
  filename: string,
  mime: string,
): voidfunction downloadBytes(
  bytes: Uint8Array | string,
  filename: string,
  mime: string,
): voidTrigger a browser download from in-memory bytes. The temporary anchor is removed and its object URL is scheduled for revocation even when DOM append or click throws.API reference →(
  workbookBytesconst workbookBytes: Uint8Array<ArrayBufferLike>const workbookBytes: Uint8Array<ArrayBufferLike>const workbookBytes: Uint8Array<ArrayBufferLike>,
  "workbook.xlsx",
  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
);

Function	Signature
`fromCsv`	`fromCsv(text: string, columns: readonly Column[]): ColumnarData`
`fromXlsxTable`	`(data: ArrayBuffer \| Uint8Array, options?: XlsxWorkbookOptions) => Promise<ColumnarData>`
`fromXlsxWorkbook`	`(data: ArrayBuffer \| Uint8Array, options?: XlsxWorkbookOptions) => Promise<WorkbookSnapshot>`
`toCsv`	`toCsv(sheet: Sheet, store: Store): string`
`toTsv`	`toTsv(range: Range, store: Store): string`
`toXlsxTable`	`(workbook: Workbook, store: Store, options?: XlsxWorkbookOptions) => Promise<Uint8Array>`
`toXlsxWorkbook`	`(snapshot: WorkbookSnapshot, options?: XlsxWorkbookOptions) => Promise<Uint8Array>`
`downloadBytes`	`downloadBytes(bytes: Uint8Array \| string, filename: string, mime: string): void`

XlsxWorkbookOptions is the shared resource contract for every table and workbook path. maxCells bounds logical accepted cells and defaults to 1_000_000; resourceLimits overrides the remaining input, archive, XML, dimension, and output budgets, which are checked before decompression and allocation and reject with a typed XlsxResourceError. signal is checked between bounded codec stages, and structured warnings surface through onWarning. Both directions materialize the complete file representation in memory; there is no streaming mode.

XLSX compatibility

Feature	Table API	Workbook API
Multiple worksheets and order	Active sheet only	Preserved
First row	Synthesized column headers	Ordinary row; no header synthesis
Formula source, including cross-sheet formulas	Exports resolved scalars	Preserved; workbook requests full recalculation on open
Cell styles, borders, number/date formats	Preserved on active-sheet export	Preserved
Merges, column widths, row heights	Preserved on active-sheet export	Preserved
Frozen panes and active worksheet	Not round-tripped	Preserved
Named ranges	Not represented	Preserved
Sheetwrite conditional formats and row groups	Not represented	Preserved in Sheetwrite metadata; warning reports that no Excel rule/outline is emitted
Boolean literals	Imported by the table reader	Preserved as native booleans
Rich text and hyperlinks	Reader-dependent flattening	Display text preserved with a structured warning
Sheetwrite validation rules	Not represented	Preserved in Sheetwrite metadata; supported list/numeric/date/text-length rules also emit native Excel validation
Protected ranges	Not represented	Preserved in Sheetwrite metadata; no Excel sheet-protection claim is made
Cell notes	Not represented	Preserved in Sheetwrite metadata and emitted as native Excel notes
External Excel validation, protection, notes, images, tables, auto-filters, conditional formatting, and VBA	Not represented	Features without Sheetwrite metadata are dropped with a structured `unsupported-feature` warning when detected

Workbook formulas are imported as formula source, not as cached results. Hydrating the returned snapshot with SheetwriteStore.fromSnapshot recompiles them into the WASM formula engine. No raw formula handles enter the serialized snapshot.

XLSX backends

XLSX uses pluggable backends. Calling a table or workbook API without its backend throws a configuration error that names both remedies: install @sheetwrite/xlsx, then import @sheetwrite/xlsx/register before calling the function. The ordinary core entry never resolves the optional codec, so normal grid bundles carry no spreadsheet-file code.

@sheetwrite/xlsx is the only concrete implementation package. Its root entry is side-effect free and exports registerXlsxBackends() plus the three named backend instances for explicit registration or wrapping. The ./register entry performs idempotent registration:

import {
  registerXlsxBackendsfunction registerXlsxBackends(): voidfunction registerXlsxBackends(): voidfunction registerXlsxBackends(): voidRegister all concrete XLSX backends with the backend-neutral core contracts.API reference →,
  sheetwriteTableExportBackendconst sheetwriteTableExportBackend: XlsxTableExportBackendconst sheetwriteTableExportBackend: XlsxTableExportBackendconst sheetwriteTableExportBackend: XlsxTableExportBackendDefault bounded first-sheet table export backend.API reference →,
  sheetwriteTableImportBackendconst sheetwriteTableImportBackend: XlsxTableImportBackendconst sheetwriteTableImportBackend: XlsxTableImportBackendconst sheetwriteTableImportBackend: XlsxTableImportBackendDefault bounded first-sheet table import backend.API reference →,
  sheetwriteWorkbookBackendconst sheetwriteWorkbookBackend: XlsxWorkbookBackendconst sheetwriteWorkbookBackend: XlsxWorkbookBackendconst sheetwriteWorkbookBackend: XlsxWorkbookBackendDeterministic optional OOXML workbook backend implemented by Sheetwrite.API reference →,
} from "@sheetwrite/xlsx";
import {
  setXlsxTableExportBackendfunction setXlsxTableExportBackend(next: XlsxTableExportBackend): voidfunction setXlsxTableExportBackend(
  next: XlsxTableExportBackend,
): voidfunction setXlsxTableExportBackend(
  next: XlsxTableExportBackend,
): voidRegisters the optional table XLSX export implementation used by core.API reference →,
  setXlsxTableImportBackendfunction setXlsxTableImportBackend(next: XlsxTableImportBackend): voidfunction setXlsxTableImportBackend(
  next: XlsxTableImportBackend,
): voidfunction setXlsxTableImportBackend(
  next: XlsxTableImportBackend,
): voidRegisters the optional table XLSX import implementation used by core.API reference →,
  setXlsxWorkbookBackendfunction setXlsxWorkbookBackend(next: XlsxWorkbookBackend): voidfunction setXlsxWorkbookBackend(
  next: XlsxWorkbookBackend,
): voidfunction setXlsxWorkbookBackend(
  next: XlsxWorkbookBackend,
): voidRegisters the optional workbook XLSX implementation used by core.API reference →,
  type XlsxTableExportBackendinterface XlsxTableExportBackendinterface XlsxTableExportBackendinterface XlsxTableExportBackendPluggable first-row-header, first-sheet table export backend.API reference →,
  type XlsxTableImportBackendinterface XlsxTableImportBackendinterface XlsxTableImportBackendinterface XlsxTableImportBackendPluggable table import backend. Parses raw .xlsx bytes into the same ColumnarData shape fromCsv returns, so host ingestion code can stay format-agnostic.API reference →,
  type XlsxWorkbookBackendinterface XlsxWorkbookBackendinterface XlsxWorkbookBackendinterface XlsxWorkbookBackendOptional backend contract for complete workbook XLSX interchange.API reference →,
} from "@sheetwrite/core";

registerXlsxBackendsfunction registerXlsxBackends(): voidfunction registerXlsxBackends(): voidfunction registerXlsxBackends(): voidRegister all concrete XLSX backends with the backend-neutral core contracts.API reference →();

// Or compose individual backends explicitly.
setXlsxTableExportBackendfunction setXlsxTableExportBackend(next: XlsxTableExportBackend): voidfunction setXlsxTableExportBackend(
  next: XlsxTableExportBackend,
): voidfunction setXlsxTableExportBackend(
  next: XlsxTableExportBackend,
): voidRegisters the optional table XLSX export implementation used by core.API reference →(sheetwriteTableExportBackendconst sheetwriteTableExportBackend: XlsxTableExportBackendconst sheetwriteTableExportBackend: XlsxTableExportBackendconst sheetwriteTableExportBackend: XlsxTableExportBackendDefault bounded first-sheet table export backend.API reference →);
setXlsxTableImportBackendfunction setXlsxTableImportBackend(next: XlsxTableImportBackend): voidfunction setXlsxTableImportBackend(
  next: XlsxTableImportBackend,
): voidfunction setXlsxTableImportBackend(
  next: XlsxTableImportBackend,
): voidRegisters the optional table XLSX import implementation used by core.API reference →(sheetwriteTableImportBackendconst sheetwriteTableImportBackend: XlsxTableImportBackendconst sheetwriteTableImportBackend: XlsxTableImportBackendconst sheetwriteTableImportBackend: XlsxTableImportBackendDefault bounded first-sheet table import backend.API reference →);
setXlsxWorkbookBackendfunction setXlsxWorkbookBackend(next: XlsxWorkbookBackend): voidfunction setXlsxWorkbookBackend(
  next: XlsxWorkbookBackend,
): voidfunction setXlsxWorkbookBackend(
  next: XlsxWorkbookBackend,
): voidRegisters the optional workbook XLSX implementation used by core.API reference →(sheetwriteWorkbookBackendconst sheetwriteWorkbookBackend: XlsxWorkbookBackendconst sheetwriteWorkbookBackend: XlsxWorkbookBackendconst sheetwriteWorkbookBackend: XlsxWorkbookBackendDeterministic optional OOXML workbook backend implemented by Sheetwrite.API reference →);

The backends share Sheetwrite's internal bounded OOXML codec, which owns OPC part resolution, XML tokenization, styles, and worksheet mapping over one audited compression primitive (fflate). It preserves formula source, worksheets, styles, merges, dimensions, frozen views, and named ranges, and it enforces the shared resource limits before decompression. The host can replace any role by implementing XlsxWorkbookBackend or the table backend contracts.