Skip to main content
ExcelWorkbook is an Office.js-like API. It follows the names and shapes in the Office JavaScript API for Microsoft Excel, so if you have written a Microsoft Excel add-in, you know most of it. It is not compatible with the Office JavaScript API. It is not a drop-in replacement, and add-in code does not run on it without changes. Some members are missing, some have a different shape, and some are extensions that the Office JavaScript API does not have. The differences are below.

Try it

Edit the script, then press Run (or Cmd+Enter). The script runs on the workbook at the right. Each run is one step of undo in the grid.

The object tree

book.getRange("Sheet1!A1:C3") takes an address with a sheet name. sheet.getRange("A1:C3") takes one on that sheet. Both accept whole rows ("3:4") and columns ("A:D").

How it differs

No Excel.run, no context, no load/sync. You hold the workbook. Every property reads the workbook now, and every assignment changes it now.
Formulas are calculated when you read. Write a formula, then read values: the value is the result of the new formula, not the cached one. See Recalculation. Arrays must match the range. values and formulas take a 2-D array with one entry per cell. An array of another shape throws, and the message names the expected size. Formats (numberFormat) also take a single value for the whole range. Files are bytes or paths. ExcelWorkbook.create() makes an empty workbook, ExcelWorkbook.fromBytes(bytes) opens one and book.toBytes() saves it. The Node entry adds open(path), save(path), toPdf and toPng. getImage is a promise. range.getImage() returns Promise<string>, not a ClientResult, because fonts and pictures load first. It also takes options that Office.js does not have, such as labels: true for row and column headers. In the browser, import @reductoai/xlsx/view once to give it a painter (see PNG). Not-found members. Members such as getItem throw when nothing matches. The …OrNullObject forms return an object with isNullObject set, as in the Office JavaScript API. Extensions. Members the Office JavaScript API lacks are marked as extensions in the type comments. The main ones are toPdf and toPng in Node.
Write formulas, not numbers you computed yourself. The workbook stays live when someone changes an input, and reading the cell back tells you whether the formula works.

Where next