Parsing options

Pass this object as the second argument of XLSX.read(data, options) or XLSX.readFile(filename, options). Options apply only where the source format can represent the feature. They do not add metadata that the input lacks.

Input representation

type	Expected input
"string"	Plain text, such as CSV or HTML
"base64"	Base64-encoded file data
"binary"	A binary string: one character per byte
"buffer"	A Node Buffer
"array"	Uint8Array, ArrayBuffer, or an array of bytes
"file"	A filesystem path (Node only)

When type is absent, read chooses from the JavaScript value. This is distinct from format detection: the spreadsheet format is detected from the content, not a file extension. Use readFile for a path rather than passing a path string to an ordinary read call.

Cells and presentation

Option	Type / default	Effect
cellFormula	boolean; true	Keep formula strings in f
cellText	boolean; true	Generate formatted display text in w
cellHTML	boolean; true	Keep rich-text HTML in h, where supported
cellNF	boolean; false	Keep number-format codes in z
cellDates	boolean	Return date cells with t: "d", rather than numeric serials
dateNF	string	Override the default date format (built-in format 14)
cellStyles	boolean	Load cell styles, row/column metadata and presentation features supported by the format
sheetStubs	boolean	Create blank cells with t: "z" for blanks that carry formatting
dense	boolean	Put cells in ws["!data"][row][column] rather than A1-keyed properties
xlfn	boolean	Retain _xlfn. prefixes in formulas
nodim	boolean	Compute the used range from cells rather than trusting the stored dimension

All cell coordinates in a dense array are zero-based. Dense mode changes the storage shape, not worksheet metadata such as !ref.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
const source = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(source, XLSX.utils.aoa_to_sheet([["Value"], [12.5]]), "Data");
const bytes = XLSX.write(source, { type: "buffer", bookType: "xlsx" });
const result = XLSX.read(bytes, { dense: true, cellText: false });
assert.equal(result.Sheets.Data["!data"][1][0].v, 12.5);
assert.equal(result.Sheets.Data["!data"][1][0].w, undefined);

Limit the read

Option	Type / default	Effect
sheetRows	number; 0 means all	Read at most this many rows per worksheet, including the header row
sheets	string, number, or array of either	Parse selected sheets by name or zero-based index
bookSheets	boolean	Stop after sheet names
bookProps	boolean	Stop after document properties

Metadata-only modes need not return the normal Sheets object. Do not assume that bookSheets: true also parsed any cell values.

Additional package data

Option	Type	Effect
bookFiles	boolean	Expose raw package parts through wb.files and wb.keys
bookVBA	boolean	Keep the macro project in wb.vbaraw
bookDeps	boolean	Parse the calculation chain
bookImages	boolean	Load embedded images where supported

Keeping VBA does not run macros. To re-emit the project, choose a macro-capable output format and the corresponding write option.

Text formats and dates

Option	Type / default	Effect
raw	boolean	Keep delimited-text values as strings instead of inferring numbers and dates
FS	string	Override the field separator in delimited text
codepage	number	Select a legacy text encoding
UTC	boolean; true	Interpret ambiguous text date-times as UTC; false uses local time
sheet	string; "Sheet1"	Name for a single-sheet input format
PRN	boolean	Allow fixed-width PRN text parsing

The read option raw is not the same setting as sheet_to_json’s raw, which chooses raw values versus formatted text when converting an existing sheet.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
const workbook = XLSX.read("Code;Amount\n0012;3.50", {
  type: "string", FS: ";", raw: true
});
assert.equal(workbook.Sheets.Sheet1.A2.v, "0012");
assert.equal(workbook.Sheets.Sheet1.B2.v, "3.50");

Template mode

Option	Type	Effect
template	boolean	Retain the XLSX/XLSM package for template edits; also use template: true when writing
skipParse	boolean	In template mode, omit construction of ordinary worksheets. Sheets is empty; SheetNames remains available
recalc	boolean	Set false to avoid asking the spreadsheet application to recalculate on open

By default, template mode requests full recalculation when the workbook already contains a calculation-properties entry. It does not create that entry when missing. With cellStyles: true, cell styles passed to template_set_aoa merge as differential changes; without it they replace the existing styling.

See Template editing and the template helper reference.

Error handling and accepted compatibility options

Option	Type	Behavior
WTF	boolean	Request errors for malformed or unsupported content rather than skipping it
password	string	Declared for API compatibility; encrypted-file reading is not supported
PPI	number or string	Screen density for width and height conversion: 72, 96 (default), 120, 144, "osx" or "win". Other values throw "Unsupported PPI <value>"

WTF is not a guarantee that every malformed document will be diagnosed. Use ordinary try/catch around reads that receive untrusted or unexpected input.