---
url: /process-functions/excel-workbook.md
description: An Excel workbook to read, write, style and save.
---

#  ExcelWorkbook

An Excel workbook to read, write, style and save.

```js
const wb = workbook.excelWorkbook(false);

wb.writeString(0, 0, "Region");
wb.writeString(0, 1, "Revenue");
wb.writeString(1, 0, "North");
wb.writeNumber(1, 1, 5000, "#,##0.00");

wb.save("exports/report.xlsx");
```

## Constructors

### workbook.excelWorkbook `workbook.excelWorkbook(isStreamingWorkbook)`  {#workbook-excelworkbook}

Creates a new, empty workbook with one sheet, `Sheet1`.

| Parameter | Type | Description |
|---|---|---|
| `isStreamingWorkbook` | `boolean` | `true` for a [streaming workbook](#streaming-workbooks), for writing very large files. `false` for a regular workbook. |

```js
const wb = workbook.excelWorkbook(false);
```

### workbook.excelWorkbook `workbook.excelWorkbook(fileName, isStreamingWorkbook, password, rowAccessWindowSize)`  {#workbook-excelworkbook-file}

Opens a workbook from a file. Its first sheet is selected.

| Parameter | Type | Description |
|---|---|---|
| `fileName` | `string` | The path of the `.xlsx` file. |
| `isStreamingWorkbook` | `boolean` | `true` for a [streaming workbook](#streaming-workbooks), for writing very large files. `false` for a regular workbook. |
| `password` | `string` | Optional. The workbook's password. Not supported for streaming workbooks. |
| `rowAccessWindowSize` | `number` | Optional. For streaming workbooks, how many rows to keep in memory. |

```js
const wb = workbook.excelWorkbook("uploads/budget.xlsx", false);
```

### workbook.fromBase64 `workbook.fromBase64(base64String, isStreamingWorkbook, password)`  {#workbook-frombase64}

Opens a workbook from base64-encoded data. Its first sheet is selected.

| Parameter | Type | Description |
|---|---|---|
| `base64String` | `string` | The workbook, base64-encoded. |
| `isStreamingWorkbook` | `boolean` | `true` for a [streaming workbook](#streaming-workbooks), for writing very large files. `false` for a regular workbook. |
| `password` | `string` | Optional. The workbook's password. Not supported for streaming workbooks. |

```js
const wb = workbook.fromBase64(base64Data, false);
```

## Overview

* **Rows and columns** start at `0`, so cell `A1` is row `0`, column `0`.
* **The current sheet:** reads and writes apply to the current sheet. Change it with [selectSheet](#selectsheet) or [createSheet](#createsheet).
* **Styling:** the `setCell` methods style a cell that has already been written.
* **Closing:** workbooks close automatically when the process finishes.

### Streaming workbooks

A streaming workbook keeps only a window of rows in memory, so it can write very large files. Rows outside the window can't be read back, so use a regular workbook when you need to read cell values.

### Reading formulas

The `read` methods work out a formula's result. If that fails, they throw an error, unless `returnCachedOnError` is `true`, which returns the result Excel last stored instead. The `readCached` methods only use the stored result, which is faster.

### Border styles

| Value | Style |
|---|---|
| `0` | None |
| `1` | Thin |
| `2` | Medium |
| `3` | Dashed |
| `4` | Dotted |
| `5` | Thick |
| `6` | Double |
| `7` | Hairline |
| `8` | Medium dashed |
| `9` | Dash-dot |
| `10` | Medium dash-dot |
| `11` | Dash-dot-dot |
| `12` | Medium dash-dot-dot |
| `13` | Slanted dash-dot |

## Methods

### createSheet `createSheet(name)` {#createsheet}

Adds a sheet and makes it the current sheet.

| Parameter | Type | Description |
|---|---|---|
| `name` | `string` | The sheet's name. It can't already be used in the workbook. |

### selectSheet `selectSheet(name)` {#selectsheet}

Makes a sheet the current sheet.

| Parameter | Type | Description |
|---|---|---|
| `name` | `string` | The sheet's name. |

### changeSheetName `changeSheetName(oldName, newName)` {#changesheetname}

Renames a sheet. The current sheet doesn't change.

| Parameter | Type | Description |
|---|---|---|
| `oldName` | `string` | The sheet's current name. |
| `newName` | `string` | The sheet's new name. |

### getSheetName `getSheetName(index)`  {#getsheetname}

Returns the name of the sheet at a position, starting at `0`.

| Parameter | Type | Description |
|---|---|---|
| `index` | `number` | The sheet's position. |

### getNumberOfSheets `getNumberOfSheets()`  {#getnumberofsheets}

Returns how many sheets the workbook has.

### writeString `writeString(row, column, value)` {#writestring}

Writes text to a cell.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |
| `value` | `string` | The text. |

### writeNumber `writeNumber(row, column, value, numberFormat)` {#writenumber}

Writes a number to a cell.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |
| `value` | `number` | The number. |
| `numberFormat` | `string` | Optional. An Excel number format, such as `"#,##0.00"`. |

### writeFormula `writeFormula(row, column, formula)` {#writeformula}

Writes a formula to a cell.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |
| `formula` | `string` | The formula, without the leading `=`, such as `"SUM(B2:B10)"`. |

### deleteRow `deleteRow(rowNumber)` {#deleterow}

Deletes a row. The rows below don't move up, so it leaves an empty row.

| Parameter | Type | Description |
|---|---|---|
| `rowNumber` | `number` | The row. |

### copyRange `copyRange(srcRange, destRange, copyValues, copyFormulas, copyStyles)` {#copyrange}

Copies a range of cells to another place on the current sheet.

| Parameter | Type | Description |
|---|---|---|
| `srcRange` | `string` | The range to copy, such as `"A1:B2"`. |
| `destRange` | `string` | Where to copy it. Only its top-left cell is used. |
| `copyValues` | `boolean` | `true` to copy the values. |
| `copyFormulas` | `boolean` | `true` to copy the formulas. |
| `copyStyles` | `boolean` | `true` to copy the styles. |

### copyRange `copyRange(srcSheetName, srcRange, destSheetName, destRange, copyValues, copyFormulas, copyStyles)` {#copyrange-sheets}

Copies a range of cells from one sheet to another.

| Parameter | Type | Description |
|---|---|---|
| `srcSheetName` | `string` | The sheet to copy from. |
| `srcRange` | `string` | The range to copy, such as `"A1:B2"`. |
| `destSheetName` | `string` | The sheet to copy to. |
| `destRange` | `string` | Where to copy it. |
| `copyValues` | `boolean` | `true` to copy the values. |
| `copyFormulas` | `boolean` | `true` to copy the formulas. |
| `copyStyles` | `boolean` | `true` to copy the styles. |

### evaluateAll `evaluateAll()` {#evaluateall}

Recalculates every formula in the workbook. Call it before saving so the stored results are up to date.

### readString `readString(row, column, returnCachedOnError)`  {#readstring}

Reads a cell as text. Numbers and booleans are converted to text. Returns `null` when the cell is empty.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |
| `returnCachedOnError` | `boolean` | Optional. `true` to return the stored result if a formula fails. |

### readNumber `readNumber(row, column, returnCachedOnError)`  {#readnumber}

Reads a cell as a number. Returns `null` when the cell is empty or holds text.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |
| `returnCachedOnError` | `boolean` | Optional. `true` to return the stored result if a formula fails. |

### readBoolean `readBoolean(row, column, returnCachedOnError)`  {#readboolean}

Reads a cell as `true` or `false`. Returns `null` when the cell is empty or isn't a boolean.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |
| `returnCachedOnError` | `boolean` | Optional. `true` to return the stored result if a formula fails. |

### readDate `readDate(row, column, format, returnCachedOnError)`  {#readdate}

Reads a date cell as text.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |
| `format` | `string` | Optional. The date format, such as `"DD/MM/YYYY"`. Defaults to `"YYYY-MM-DD"`. |
| `returnCachedOnError` | `boolean` | Optional. `true` to return the stored result if a formula fails. |

### readCachedString `readCachedString(row, column)`  {#readcachedstring}

Reads a cell as text, using the result Excel last stored.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |

### readCachedNumber `readCachedNumber(row, column)`  {#readcachednumber}

Reads a cell as a number, using the result Excel last stored.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |

### toMatrix `toMatrix(a1Range, cachedOnly)`  {#tomatrix}

Reads a range of the current sheet as an array of rows, each an array of values. Numbers, booleans and text keep their types.

| Parameter | Type | Description |
|---|---|---|
| `a1Range` | `string` | The range, such as `"A1:D20"`. Use `""` for every cell with a value. |
| `cachedOnly` | `boolean` | `true` to use the results Excel last stored, instead of working out formulas. Much faster on large sheets. |

### toMatrix `toMatrix(cachedOnly)`  {#tomatrix-sheet}

Reads every cell with a value on the current sheet. The same as `toMatrix("", cachedOnly)`.

| Parameter | Type | Description |
|---|---|---|
| `cachedOnly` | `boolean` | `true` to use the results Excel last stored, instead of working out formulas. |

### setCellFontColor `setCellFontColor(rowNum, colNum, hexColor)` {#setcellfontcolor}

Sets a cell's text colour.

| Parameter | Type | Description |
|---|---|---|
| `rowNum` | `number` | The row. |
| `colNum` | `number` | The column. |
| `hexColor` | `string` | The colour, such as `"#FF0000"`. |

### setCellBackgroundColor `setCellBackgroundColor(rowNum, colNum, hexColor)` {#setcellbackgroundcolor}

Sets a cell's background colour.

| Parameter | Type | Description |
|---|---|---|
| `rowNum` | `number` | The row. |
| `colNum` | `number` | The column. |
| `hexColor` | `string` | The colour, such as `"#EEEEEE"`. |

### setCellAlignment `setCellAlignment(rowNum, colNum, horizontal, vertical)` {#setcellalignment}

Sets how a cell's content is aligned.

| Parameter | Type | Description |
|---|---|---|
| `rowNum` | `number` | The row. |
| `colNum` | `number` | The column. |
| `horizontal` | `string` | `"left"`, `"center"`, `"right"` or `"justify"`. Use `""` to leave it as it is. |
| `vertical` | `string` | `"top"`, `"center"`, `"bottom"` or `"justify"`. Use `""` to leave it as it is. |

### setCellBorder `setCellBorder(rowNum, colNum, borderStyle)` {#setcellborder}

Sets the border on all four sides of a cell.

| Parameter | Type | Description |
|---|---|---|
| `rowNum` | `number` | The row. |
| `colNum` | `number` | The column. |
| `borderStyle` | `number` | The [border style](#border-styles). |

### setCellBorderSide `setCellBorderSide(rowNum, colNum, borderStyle, side)` {#setcellborderside}

Sets the border on one side of a cell.

| Parameter | Type | Description |
|---|---|---|
| `rowNum` | `number` | The row. |
| `colNum` | `number` | The column. |
| `borderStyle` | `number` | The [border style](#border-styles). |
| `side` | `string` | `"top"`, `"bottom"`, `"left"` or `"right"`. |

### getCellAddress `getCellAddress(row, column)`  {#getcelladdress}

Returns a cell's address, such as `"A1"` for row `0`, column `0`.

| Parameter | Type | Description |
|---|---|---|
| `row` | `number` | The row. |
| `column` | `number` | The column. |

### getColumnName `getColumnName(column)`  {#getcolumnname}

Returns a column's letter, such as `"A"` for `0` and `"AA"` for `26`.

| Parameter | Type | Description |
|---|---|---|
| `column` | `number` | The column. |

### save `save(fileName)` {#save}

Saves the workbook to a file, replacing it if it exists.

| Parameter | Type | Description |
|---|---|---|
| `fileName` | `string` | The path to save to, such as `"exports/report.xlsx"`. |

### toBase64 `toBase64()`  {#tobase64}

Returns the workbook, base64-encoded, such as to attach to an email.

### close `close()`  {#close}

Closes the workbook. Workbooks close automatically when the process finishes, so only call this to free memory early.

## Examples

### Build a styled report

```js
const wb = workbook.excelWorkbook(false);
wb.changeSheetName("Sheet1", "Sales");

const headers = ["Region", "Units", "Revenue"];
headers.forEach((header, column) => {
    wb.writeString(0, column, header);
    wb.setCellBackgroundColor(0, column, "#EEEEEE");
    wb.setCellBorderSide(0, column, 1, "bottom");
});

wb.writeString(1, 0, "North");
wb.writeNumber(1, 1, 120);
wb.writeNumber(1, 2, 5000, "#,##0.00");

wb.writeString(2, 0, "South");
wb.writeNumber(2, 1, 85);
wb.writeNumber(2, 2, 4200, "#,##0.00");

wb.writeString(3, 0, "Total");
wb.writeFormula(3, 2, "SUM(C2:C3)");

wb.evaluateAll();
wb.save("exports/sales.xlsx");
```

### Read a sheet

::: code-group

```js [read.js]
const wb = workbook.excelWorkbook("uploads/budget.xlsx", false);
wb.selectSheet("Budget");

for (const row of wb.toMatrix("A2:C4", false)) {
    console.log(row.join(", "));
}
```

```text [Output]
North, 2026, 5000
South, 2026, 4200
East, 2026, 3900
```

:::

### Email a workbook

```js
const wb = workbook.excelWorkbook(false);
wb.writeString(0, 0, "Hello");

new EmailBuilder()
    .to("user@example.com")
    .subject("Report")
    .body("The report is attached.")
    .attachBase64("report.xlsx", wb.toBase64())
    .send();
```

## Related

* [workbook.workbookFromQuery](/process-functions/workbook-workbookfromquery)
* [workbook.columnIndexToName](/process-functions/workbook-columnindextoname)
* [EmailBuilder](/process-functions/emailbuilder)