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

# @reductoai/xlsx-editor

The batteries-included editor. Guide: [Editor](https://docs.reducto.ai/office/xlsx/ui/editor.md).

## `mountXlsxEditor()`

```ts theme={null}
function mountXlsxEditor(
  target: HTMLElement,
  options?: XlsxEditorOptions,
): XlsxEditorHandle
```

Import from `@reductoai/xlsx-editor`.

## `XlsxEditorOptions`

Import from `@reductoai/xlsx-editor`.

| Name | Type | Description |
| - | - | - |
| `fonts?` | `FaceProvider` | The faces cells and charts paint with; `fontsUrl` is then ignored. |
| `fontsUrl?` | `string` | Where the `@reductoai/portable-fonts` files are served from. Default: the npm CDN. |
| `functions?` | `readonly XlsxFunction[]` | Functions formulas may call, as `=ACME.QR(A1)`; each workbook the editor opens registers them. |
| `hooks?` | `XlsxEditorHooks` | Prompts Excel shows (merge, Data Validation, Row Height) and a hook after every change. |
| `images?` | `ImageLoader \| false` | What `IMAGE` fetches pictures with. Default `fetchImage`: the site must allow this page's origin (CORS), or the cell shows #CONNECT!. `false` fetches nothing, and a new `IMAGE` shows #BLOCKED!. |
| `keybindings?` | `KeybindingOptions` | Changes to Excel's keys, where the user's own changes are kept, and whether the user may make them. |
| `proxyUrl?` | `string` | Sends license checks and usage events through your backend instead of straight to Reducto: the URL where `licenseProxy` from `@reductoai/xlsx/license-proxy` is mounted. Required: a licensed editor will not run in a browser without it. |
| `readOnly?` | `boolean` | A viewer's grid: selection, sheets, Find and Copy work; every edit is refused. |
| `side?` | `EditorSlot` | A task pane right of the grid, under the Home tab, as Excel's panes sit. The host element is `display: contents`, so what the slot appends is the pane itself. |
| `toolbar?` | `boolean` | The Home tab above the grid. Default on. |
| `userName?` | `string` | The name new comments are posted under. |
| `workbook?` | `Uint8Array \| Workbook` | Opened as soon as the editor mounts: the bytes of an .xlsx or .xlsm file, or a workbook. |

## `XlsxEditorHandle`

Import from `@reductoai/xlsx-editor`.

| Name | Type | Description |
| - | - | - |
| `model` | `XlsxEditorModel` | |
| `destroy()` | `() => void` | |
| `open()` | `(workbook: Uint8Array<ArrayBufferLike> \| Workbook, options?: WorkbookViewOptions) => Workbook` | Opens a file's bytes or a workbook in place of the current one; returns the workbook. |
| `save()` | `() => Uint8Array<ArrayBufferLike> \| null` | The workbook as .xlsx bytes, with every edit; null while none is open. |

## `XlsxEditorModel`

Import from `@reductoai/xlsx-editor`.

### XlsxEditorModel properties

| Name | Type | Description |
| - | - | - |
| `activeIsNumber` | `boolean` | The active cell holds a number, so Sort reads Smallest to Largest as in Excel. |
| `canRedo` | `boolean` | |
| `canUndo` | `boolean` | |
| `cellWindow` | `CellWindow \| null` | The note or link window; null when shut. |
| `chart` | `ChartPaneState \| null` | The one selected chart, for the Format pane; null when the selection is anything else. |
| `chartPaneOpen` | `boolean` | Whether the Format pane is open; it shows while a chart is selected. |
| `circular` | `string` | Excel's status bar note while a formula is on a cycle: "Circular References: B1", or no cell when the cycle is on another sheet. |
| `customizableKeys` | `boolean` | read-only The Keyboard Shortcuts window is offered. |
| `dirty` | `boolean` | The workbook changed since it opened or since `save()` or `markSaved()`. |
| `editor` | `XlsxEditor \| null` | |
| `error` | `string` | |
| `errorCheckOpen` | `boolean` | Formulas > Error Checking. |
| `filtered` | `boolean` | The active cell's table or the sheet has a filtered list, so Clear and Reapply are on. |
| `findText` | `string` | What Find looked for last; the window opens with it. |
| `format` | `CellFormat \| null` | |
| `frozen` | `Frozen` | The panes frozen on the active sheet; Freeze Panes offers Unfreeze while any are. |
| `functions` | `readonly XlsxFunction[]` | Functions formulas may call, registered on every workbook this editor opens. |
| `gridlines` | `boolean` | Whether the active sheet shows its gridlines. |
| `headings` | `boolean` | Whether the active sheet shows its row and column headings. |
| `imageLoader` | `ImageLoader \| undefined` | What `IMAGE` fetches with in every workbook this editor opens that has no loader of its own. |
| `inTable` | `boolean` | The active cell sits in a table, so Clear Rules offers This Table. |
| `keys` | `XlsxKeymap` | read-only Every key's command; rebind with `keys.bind` or the `keybindings` option. |
| `painter` | `{ from: CellBlock; sticky: boolean } \| null` | Format Painter's source while it is on; `sticky` keeps it on after a paint. |
| `pen` | `PenState \| null` | Draw Borders' pen while it is on; its colour and line stay for the next stroke. |
| `penColor` | `string` | |
| `penLine` | `string` | |
| `prompt` | `{ message: string; notice?: boolean; then: () => void } \| null` | Excel's OK/Cancel question; OK calls `then`. A `notice` has OK alone. Null when none is open. |
| `readOnly` | `boolean` | A viewer's grid: selection, sheets, Find and Copy work; every edit is refused. |
| `recentFunctions` | `string[]` | Insert Function's Most Recently Used list, newest first. |
| `selection` | `EditorSelection \| null` | |
| `ui` | `XlsxKeyUi` | read-only |
| `version` | `number` | Bumps on every edit, selection or sheet change; a host derives its own state from it. |
| `view` | `WorkbookView \| null` | |
| `watchOpen` | `boolean` | Formulas > Watch Window is open; the cells it watches live in the sheets' `<cellWatches>`. |
| `clipboard` | `string` | read-only The text the last Copy or Cut gave, for the system clipboard. |

### `activeCellBox()`

```ts theme={null}
activeCellBox(): DOMRect | undefined
```

Where the cell window opens: beside the active cell.

### `addWatch()`

```ts theme={null}
addWatch(reference: string): boolean
```

Adds every cell of `reference` to the Watch Window; false, with the error set, when it names no cells.

### `ask()`

```ts theme={null}
ask(title: string, value: string): string | null
```

### `attach()`

```ts theme={null}
attach(container: HTMLElement): void
```

The grid's element; a workbook opened before it exists waits for it.

### `borderPen()`

```ts theme={null}
borderPen(mode: PenMode | null): void
```

Draw Border, Draw Border Grid or Erase Border; the same mode again turns the pen off.

### `cancelFunction()`

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

### `cancelPasteName()`

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

### `circleInvalid()`

```ts theme={null}
circleInvalid(): number
```

Circle Invalid Data on the active sheet; the count of cells ringed.

### `clearCircles()`

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

### `copyAsPicture()`

```ts theme={null}
copyAsPicture(appearance: PictureAppearance): Promise<boolean>
```

The selection's picture onto the system clipboard, where a paste takes it in as a picture.

### `designChart()`

```ts theme={null}
designChart(set: ChartDesignPatch): void
```

A Chart Design pick on the selected chart.

### `destroy()`

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

### `editChartTextAt()`

```ts theme={null}
editChartTextAt(clientX: number, clientY: number): boolean
```

Edits the picked title's text in place, the caret where the click landed.

### `endChartText()`

```ts theme={null}
endChartText(cancel?: boolean): void
```

### `external()`

```ts theme={null}
external<T>(run: () => Promise<T>): Promise<T>
```

Runs an edit made around the grid (a script, an agent) on `view.edits.excel` as one undo
step; the grid then shows what it did, sheets added, moved or deleted included.

### `find()`

```ts theme={null}
find(query: FindQuery, step?: -1 | 1): FoundCell | null
```

Find Next or Find Previous from the active cell; the grid goes to the match.

### `findAll()`

```ts theme={null}
findAll(query: FindQuery): FoundCell[]
```

### `formatChart()`

```ts theme={null}
formatChart(set: ChartFormatPatch, group?: string): void
```

Formats the picked element; a slider drag sends one `group`.

### `formatPainter()`

```ts theme={null}
formatPainter(sticky?: boolean): void
```

Format Painter: holds the selection's formats until the next cells picked with the mouse take
them. A double-click keeps it on until Escape or the button again, as in Excel.

### `goTo()`

```ts theme={null}
goTo(at: { c: number; r: number; sheet: number }): void
```

Selects a cell Find All listed.

### `group()`

```ts theme={null}
group(ungroup: boolean): void
```

Group or Ungroup: whole lines go at once; on cells Excel first asks Rows or Columns.

### `groupDetail()`

```ts theme={null}
groupDetail(show: boolean): void
```

Show Detail or Hide Detail on the selection; whole lines act on their own axis only.

### `hasBackground()`

```ts theme={null}
hasBackground(): boolean
```

Page Layout > Background: true when the active sheet has a picture, so the button reads Delete Background.

### `input()`

```ts theme={null}
input(r: number, c: number, sheet?: number): string
```

What the cell editor opens with: the formula, else the value.

### `insertChart()`

```ts theme={null}
insertChart(chartType: string, combo?: { chartType: string; secondary?: boolean }): void
```

Insert > Chart: Excel centres the new chart in the cells in view and selects it.

### `insertFunction()`

```ts theme={null}
insertFunction(name: string, args: string[]): void
```

OK in Function Arguments: the call goes in where Shift+F3 was pressed and the formula is entered.

### `insertPicture()`

```ts theme={null}
insertPicture(
  file: File,
  at?: { left: number; top: number } | null,
  inCell?: boolean,
): Promise<void>
```

A picture file at the active cell, or at `at` (points from A1's corner); `inCell` makes it the cell's value.

### `markSaved()`

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

The host kept the workbook another way, such as its own download of `Workbook.save()`.

### `menu()`

```ts theme={null}
menu(target: GridMenuTarget): MenuEntry[]
```

Excel's right-click menu at `target`, over the grid's current selection.

### `merge()`

```ts theme={null}
merge(apply: () => RemoteMerge): void
```

Lands another writer's change: the grid repaints and keeps the selection on its cells.

### `open()`

```ts theme={null}
open(wb: Workbook, options?: WorkbookViewOptions): void
```

### `openAdvancedFilter()`

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

Data > Advanced: Advanced Filter on the list around the selection.

### `openCellWindow()`

```ts theme={null}
openCellWindow(kind: WindowKind): void
```

Opens the note or link window on the active cell; a chart or shape selection has none.

### `openCfRule()`

```ts theme={null}
openCfRule(edit?: CfRuleRow | null, scope?: CfScope | null): void
```

New Formatting Rule (`edit` null) or Edit Rule; from Manage Rules (`scope`) it goes back there.

### `openCfRules()`

```ts theme={null}
openCfRules(scope?: CfScope): void
```

Conditional Formatting > Manage Rules, showing the rules of the selection or the sheet.

### `openConsolidate()`

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

Data > Consolidate, written from the active cell.

### `openCopyPicture()`

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

Home > Copy > Copy as Picture.

### `openCreateNames()`

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

Formulas > Create from Selection.

### `openDataTable()`

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

Data > What-If Analysis > Data Table, over the selection.

### `openDefineName()`

```ts theme={null}
openDefineName(edit?: NameRow | null, fromManager?: boolean): void
```

Define Name (`edit` null) or Name Manager's Edit; a new name refers to the selection.

### `openFillAcross()`

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

Home > Fill > Across Worksheets, while sheets are grouped.

### `openGoalSeek()`

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

Data > What-If Analysis > Goal Seek, with the active cell as the Set cell.

### `openMergeStyles()`

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

Home > Cell Styles > Merge Styles: copies the styles of another workbook in.

### `openMoveChart()`

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

Chart Design > Move Chart on the selected chart.

### `openNames()`

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

Formulas > Name Manager.

### `openNewCellStyle()`

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

Home > Cell Styles > New Cell Style: a style by example of the active cell.

### `openPageSetup()`

```ts theme={null}
openPageSetup(tab?: "Page" | "Margins" | "Header/Footer" | "Sheet"): void
```

Page Layout > Page Setup, on `tab` (Custom Margins opens Margins).

### `openPasteName()`

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

F3 on the grid, or Use in Formula > Paste Names: nothing when no name is usable, as in Excel.

### `openProtect()`

```ts theme={null}
openProtect(target: "workbook" | "sheet"): void
```

Review > Protect Sheet or Protect Workbook: the dialog when it is off, the password prompt when a
password guards it, and straight off when none does, as Excel does.

### `openRemoveDuplicates()`

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

Data > Remove Duplicates on the list around the selection; Excel's refusals show as the error.

### `openReportConnections()`

```ts theme={null}
openReportConnections(name?: string): void
```

Slicer > Report Connections for `name`, or for the one selected slicer; a table slicer has none.

### `openRule()`

```ts theme={null}
openRule(dialog: RuleDialog): void
```

Opens a quick rule dialog of Conditional Formatting over the selection.

### `openScenarios()`

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

Data > What-If Analysis > Scenario Manager for the active sheet.

### `openSelectData()`

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

Chart Design > Select Data on the selected chart.

### `openSeries()`

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

Home > Fill > Series: opens Excel's Series window on the selection.

### `openSlicerSettings()`

```ts theme={null}
openSlicerSettings(name?: string): void
```

Slicer Settings for `name`, or for the one selected slicer.

### `openSparkEdit()`

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

Sparkline > Edit Data > Edit Group Location & Data: Create Sparklines on the active group.

### `openSparklines()`

```ts theme={null}
openSparklines(type: SparkKind): void
```

Insert > Sparklines: opens Create Sparklines for Line, Column or Win/Loss.

### `openSparkSettings()`

```ts theme={null}
openSparkSettings(mode: SparkSettingsMode): void
```

Sparkline > Edit Data > Hidden & Empty Cells, or Axis > Custom Value for the minimum or maximum.

### `openSubtotal()`

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

Data > Subtotal on the list around the selection; outside a list it says so instead.

### `openTextColumns()`

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

Data > Text to Columns, over a one-column selection.

### `openValidation()`

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

Data > Data Validation over the selection, after Excel's prompt when its cells differ.

### `pickBackground()`

```ts theme={null}
pickBackground(): Promise<void>
```

Page Layout > Background: the file picker, then the picture tiled behind the active sheet.

### `pickChartPart()`

```ts theme={null}
pickChartPart(part: string): void
```

Picks the element the Format pane edits, from its list or a click on the chart.

### `pickChartPartAt()`

```ts theme={null}
pickChartPartAt(clientX: number, clientY: number): boolean
```

The element under a pointer on the selected chart, as Excel's second click picks it.

### `pickPicture()`

```ts theme={null}
pickPicture(inCell?: boolean): Promise<void>
```

Insert > Picture: the file picker, then the picture over the cells at the active cell, or in it.

### `replace()`

```ts theme={null}
replace(query: FindQuery, by: string, all: boolean): number
```

Replace or Replace All; the count of cells changed.

### `run()`

```ts theme={null}
run(command: XlsxCommand): EditResult
```

### `save()`

```ts theme={null}
save(): Uint8Array<ArrayBufferLike> | null
```

### `setPeers()`

```ts theme={null}
setPeers(peers: PeerSelection[]): void
```

Other writers' selections on the grid.

### `setPen()`

```ts theme={null}
setPen(set: { color?: string; line?: string }): void
```

Line Color and Line Style set the pen and turn Draw Border on, as Excel does.

### `setReadOnly()`

```ts theme={null}
setReadOnly(on: boolean): void
```

Mounts the grid again over the same session, so shared edits and the user's place stay.

### `shown()`

```ts theme={null}
shown(r: number, c: number, sheet?: number): string
```

The cell's text as the grid shows it.

### `stepNote()`

```ts theme={null}
stepNote(step: -1 | 1): void
```

Review > Next or Previous: selects the next note or comment and opens it.

### `stopPainter()`

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

### `stopPen()`

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

### `sync()`

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

Reads the grid selection and the history again, after an edit made around the model.

### `toggleSplit()`

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

View > Split: on at the active cell, or off; frozen panes become a split at the same place, as in Excel.

### `useInFormula()`

```ts theme={null}
useInFormula(name: string): void
```

Use in Formula and Paste Name's OK: the name goes in at the caret, or starts `=name`.

## `XlsxEditorHooks`

The confirm hooks answer Excel's OK/Cancel questions; without one the editor's own prompt asks.

Import from `@reductoai/xlsx-editor`.

| Name | Type | Description |
| - | - | - |
| `afterChange?` | `() => void` | After every edit or selection change; a shared session sends what changed from here. |
| `ask?` | `(title: string, value: string) => string \| null` | Asks for a value a menu row needs (Row Height, Rename); null when the user cancels. |
| `confirmJustify?` | `() => boolean` | Asks before Fill > Justify writes below the selection; Excel's prompt says the text will extend. |
| `confirmMerge?` | `(how: MergeHow) => boolean` | Asks before a merge drops values; Excel's own prompt says only the upper-left value stays. |
| `confirmValidation?` | `(message: string) => boolean` | Asks before Data Validation extends one rule over the selection or erases several; Excel's own prompts. |

## `watch()`

```ts theme={null}
function watch<T>(read: () => T, onChange: (value: T) => void): () => void
```

Calls `onChange` after any field `read` reads changes; returns the stop.

Import from `@reductoai/xlsx-editor`.
