> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

`ExcelWorkbook` is an Office.js-like API. It follows the names and shapes in the [Office JavaScript API](https://learn.microsoft.com/en-us/javascript/api/excel) 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.

```ts theme={null}
// `workbook` is the open workbook. Each run is one undo step in the grid.
import type { ExcelWorkbook } from "@reductoai/xlsx/officejs";

declare const workbook: ExcelWorkbook;

const sheet = workbook.worksheets.getActiveWorksheet();
sheet.name = "Sales";

sheet.getRange("A1:D1").values = [["Region", "Units", "Price", "Revenue"]];
sheet.getRange("A2:C5").values = [
  ["North", 120, 9.5],
  ["South", 95, 11],
  ["East", 143, 8.75],
  ["West", 80, 12.25],
];
sheet.getRange("D2:D5").formulas = [["=B2*C2"], ["=B3*C3"], ["=B4*C4"], ["=B5*C5"]];
sheet.getRange("A6:D6").formulas = [["Total", "=SUM(B2:B5)", "", "=SUM(D2:D5)"]];

const header = sheet.getRange("A1:D1").format;
header.font.bold = true;
header.font.color = "#FFFFFF";
header.fill.color = "#217346";
sheet.getRange("A6:D6").format.font.bold = true;
sheet.getRange("C2:D6").numberFormat = "$#,##0.00";
sheet.getRange("A:D").format.columnWidth = 72;

for (const old of sheet.charts.items) old.delete();
const chart = sheet.charts.add("ColumnClustered", sheet.getRange("A1:B5"));
chart.title.text = "Units by region";
chart.setPosition("A8", "E22");

console.log("Revenue:", sheet.getRange("D6").values[0][0]);
```

## The object tree

```mermaid theme={null}
flowchart LR
  wb[ExcelWorkbook] --> ws[worksheets]
  wb --> names["names: defined names"]
  wb --> fn["functions: call a worksheet function"]
  wb --> app["application: calculation mode, calculate(), iterative calculation"]
  ws --> sheet[ExcelWorksheet]
  sheet --> range["getRange('A1:C3'): ExcelRange with values, formulas, numberFormat, format"]
  sheet --> tables["tables: tables and their rows and columns"]
  sheet --> charts["charts: charts over a block of cells"]
  sheet --> fp[freezePanes]
```

`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.

```ts theme={null}
// Office JavaScript API, in a Microsoft Excel add-in
await Excel.run(async (context) => {
  const range = context.workbook.worksheets.getItem("Sheet1").getRange("C1");
  range.load("values");
  await context.sync();
  console.log(range.values);
});
```

```ts theme={null}
// @reductoai/xlsx
import { ExcelWorkbook } from "@reductoai/xlsx/officejs";

const book = ExcelWorkbook.fromBytes(bytes);
console.log(book.worksheets.getItem("Sheet1").getRange("C1").values);
```

**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](https://docs.reducto.ai/office/xlsx/rendering/recalculation.md).

**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](https://docs.reducto.ai/office/xlsx/rendering/png.md#from-the-js-api)).

**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.

> [!TIP]
>
> 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

* [Node](https://docs.reducto.ai/office/xlsx/js-api/node.md): open, edit, save and export files.
* [Browser](https://docs.reducto.ai/office/xlsx/js-api/browser.md): edit bytes in a page.
* [ExcelWorkbook](https://docs.reducto.ai/office/xlsx/api/excel-workbook.md): the reference.
