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

# ExcelWorkbook

The workbook. Open or create one, then edit it through `worksheets`, `names` and the other collections. [Concepts](https://docs.reducto.ai/office/xlsx/js-api/concepts.md) explains the model.

## `ExcelWorkbook`

Office.js-shaped facade over an .xlsx (`Excel.Workbook`). Handles read the live workbook and
every edit applies at once: there is no load()/sync() protocol. Members Office.js lacks are
marked as extensions.

Import from `@reductoai/xlsx/officejs`.

### ExcelWorkbook properties

| Name | Type | Description |
| - | - | - |
| `application` | `ExcelApplication` | read-only |
| `model` | `Workbook` | read-only |
| `names` | `NamedItemCollection` | read-only |
| `pivotTables` | `PivotTableCollection` | read-only |
| `tables` | `TableCollection` | read-only |
| `worksheets` | `WorksheetCollection` | read-only |
| `calculationEngineVersion` | `number` | read-only `calcPr calcId`: the engine version that last calculated the file; 0 when unknown. |
| `chartDataPointTrack` | `boolean` | Chart formatting and labels follow their data point when the data is sorted or moved. |
| `comments` | `ExcelCommentCollection` | read-only |
| `customXmlParts` | `CustomXmlPartCollection` | read-only |
| `functions` | `Functions` | read-only |
| `linkedWorkbooks` | `LinkedWorkbookCollection` | read-only |
| `notes` | `ExcelNoteCollection` | read-only |
| `pivotTableStyles` | `PivotTableStyleCollection` | read-only |
| `properties` | `DocumentProperties` | read-only |
| `protection` | `WorkbookProtection` | read-only |
| `readOnly` | `boolean` | read-only The file is always editable here. |
| `slicers` | `SlicerCollection` | read-only |
| `slicerStyles` | `SlicerStyleCollection` | read-only |
| `styles` | `StyleCollection` | read-only |
| `tableStyles` | `TableStyleCollection` | read-only |
| `timelineStyles` | `TimelineStyleCollection` | read-only |
| `usePrecisionAsDisplayed` | `boolean` | `calcPr fullPrecision="0"`: turning it on rounds every number to the digits its format shows. |
| `userEmail` | `string` | Extension: the email of new comments' author, empty when unknown. |
| `userName` | `string` | Extension (VBA `Application.UserName`): the author of new notes and comments. |

### `ExcelWorkbook.create()`

```ts theme={null}
static create(): ExcelWorkbook
```

A workbook as Excel makes a new one: one empty "Sheet1".

### `ExcelWorkbook.fromBytes()`

```ts theme={null}
static fromBytes(bytes: Uint8Array): ExcelWorkbook
```

### `ExcelWorkbook.getActiveCell()`

```ts theme={null}
getActiveCell(): ExcelRange
```

The active cell of the active worksheet, as the file records it.

### `ExcelWorkbook.getChartSheetChart()`

```ts theme={null}
getChartSheetChart(name: string): ExcelChart
```

Extension (Office.js has no chart sheets): the chart that fills chart sheet `name`, as VBA's
`Workbook.Charts(name)` gives it. Its position and size are the sheet's and cannot change.

### `ExcelWorkbook.getRange()`

```ts theme={null}
getRange(address: string): ExcelRange
```

Extension: an address such as "Sheet1!A1:B2" or a defined name, on whichever sheet it names.

### `ExcelWorkbook.insertWorksheetsFromBase64()`

```ts theme={null}
insertWorksheetsFromBase64(
  base64File: string,
  options?: InsertWorksheetOptions,
): ClientResult<string[]>
```

Copies worksheets of another .xlsx in, with their formats, drawings and tables; comments,
pivot tables and controls stay behind. A taken name becomes "Name (2)", as in Excel.

### `ExcelWorkbook.set()`

```ts theme={null}
set(
  properties: ExcelWorkbook | UpdateData<ExcelWorkbook>,
  options?: UpdateOptions,
): void
```

Sets several properties at once; a navigation member takes a nested batch.

### `ExcelWorkbook.toBytes()`

```ts theme={null}
toBytes(): Uint8Array
```

Extension: the package with every edit written.

## Node additions

### `ExcelWorkbook.create()` (node)

```ts theme={null}
static create(): ExcelWorkbook
```

A workbook as Excel makes a new one: one empty "Sheet1".

### `ExcelWorkbook.fromBytes()` (node)

```ts theme={null}
static fromBytes(bytes: Uint8Array): ExcelWorkbook
```

### `ExcelWorkbook.open()` (node)

```ts theme={null}
static open(path: string): Promise<ExcelWorkbook>
```

### `ExcelWorkbook.save()` (node)

```ts theme={null}
save(path: string): Promise<void>
```

Writes to `path`; the facade never writes the source file in place.

### `ExcelWorkbook.toPdf()` (node)

```ts theme={null}
toPdf(
  path?: string,
  options?: SheetPictureOptions,
): Promise<Uint8Array<ArrayBufferLike>>
```

One PDF page per sheet, in points at 0.75 pt per pixel; writes `path` when given.

### `ExcelWorkbook.toPng()` (node)

```ts theme={null}
toPng(options?: ToPngOptions): Promise<RenderedSheet[]>
```

One PNG per sheet.

## `SheetPictureOptions`

Import from `@reductoai/xlsx/node`.

| Name | Type | Description |
| - | - | - |
| `gridlines?` | `boolean` | Show gridlines. Default false, as Excel prints. |
| `labels?` | `boolean` | Column letters and row numbers around the cells, so a reader can name a cell. Default false. |
| `range?` | `string` | An A1 range such as "B2:F20" or "Sheet2!A1:D10". Default: each sheet's used range. |
| `sheets?` | `(string \| number)[]` | Sheet names or zero-based indices. Default: every visible sheet. |

## `ToPngOptions`

Import from `@reductoai/xlsx/node`.

```ts theme={null}
type ToPngOptions = SheetPictureOptions & { scale?: number }
```

## `RenderedSheet`

Import from `@reductoai/xlsx/node`.

| Name | Type | Description |
| - | - | - |
| `height` | `number` | |
| `png` | `Buffer` | |
| `sheet` | `string` | |
| `width` | `number` | |

## `WorksheetCollection`

`Excel.WorksheetCollection`: `getItem` takes a name or an id.

Import from `@reductoai/xlsx/officejs`.

### WorksheetCollection properties

| Name | Type | Description |
| - | - | - |
| `items` | `T[]` | read-only |

### `WorksheetCollection.add()`

```ts theme={null}
add(name?: string): ExcelWorksheet
```

Appends a sheet; without a name it takes the next free "SheetN".

### `WorksheetCollection.getActiveWorksheet()`

```ts theme={null}
getActiveWorksheet(): ExcelWorksheet
```

### `WorksheetCollection.getCount()`

```ts theme={null}
getCount(visibleOnly?: boolean): ClientResult<number>
```

### `WorksheetCollection.getFirst()`

```ts theme={null}
getFirst(visibleOnly?: boolean): ExcelWorksheet
```

### `WorksheetCollection.getItem()`

```ts theme={null}
getItem(key: string): ExcelWorksheet
```

### `WorksheetCollection.getItemAt()`

```ts theme={null}
getItemAt(index: number): ExcelWorksheet
```

### `WorksheetCollection.getItemOrNullObject()`

```ts theme={null}
getItemOrNullObject(key: string): ExcelWorksheet & { isNullObject: boolean }
```

Office.js null-object variant; inspect `isNullObject` before other members.

### `WorksheetCollection.getLast()`

```ts theme={null}
getLast(visibleOnly?: boolean): ExcelWorksheet
```

## `ExcelApplication`

Import from `@reductoai/xlsx/officejs`.

### ExcelApplication properties

| Name | Type | Description |
| - | - | - |
| `iterativeCalculation` | `IterativeCalculation` | read-only |
| `calculationEngineVersion` | `number` | read-only |
| `calculationMode` | `CalculationMode` | The mode Excel calculates the file in; this facade recalculates every edit whatever it says. |
| `calculationState` | `"Done"` | read-only Every edit recalculates at once, so nothing is ever pending. |

### `ExcelApplication.calculate()`

```ts theme={null}
calculate(calculationType?: "Recalculate" | "Full" | "FullRebuild"): void
```

### `ExcelApplication.set()`

```ts theme={null}
set(
  properties: ExcelApplication | UpdateData<ExcelApplication>,
  options?: UpdateOptions,
): void
```

Sets several properties at once; a navigation member takes a nested batch.

### `ExcelApplication.suspendApiCalculationUntilNextSync()`

```ts theme={null}
suspendApiCalculationUntilNextSync(): void
```

Edits apply at once here, so there is nothing to suspend.

### `ExcelApplication.suspendScreenUpdatingUntilNextSync()`

```ts theme={null}
suspendScreenUpdatingUntilNextSync(): void
```

### `ExcelApplication.union()`

```ts theme={null}
union(first: ExcelRange | RangeAreas, second: ExcelRange | RangeAreas): RangeAreas
```

The two ranges' areas as one; both must be on the same sheet.

## `IterativeCalculation`

`Excel.IterativeCalculation`: the workbook's `calcPr` iteration settings. Setting one recalculates.

Import from `@reductoai/xlsx/officejs`.

### IterativeCalculation properties

| Name | Type | Description |
| - | - | - |
| `enabled` | `boolean` | |
| `maxChange` | `number` | Iteration stops once no value changes by more than this; Excel's default is 0.001. |
| `maxIteration` | `number` | Passes over circular cells per recalc; Excel's default is 100. |

### `IterativeCalculation.set()`

```ts theme={null}
set(
  properties: IterativeCalculation | UpdateData<IterativeCalculation>,
  options?: UpdateOptions,
): void
```

Sets several properties at once; a navigation member takes a nested batch.
