Spreadsheet API

Complete API reference for @oge-ui/spreadsheet. Everything that is not markup — the xlsx reader, the Excel-measured layout and paint, the selection, keyboard map, find, copy and the announcements — is the framework-free @oge-ui/spreadsheet-engine, shared with the React viewer; live demos are on the overview page.

Properties Methods Events Types

OgeSpreadsheet

oge-spreadsheet

Properties 12

Content

Name	Type	Default	Description
`source`	`OgeSpreadsheetSource \| null`	`null`	The workbook to open: bytes, a `Blob` / `File`, or a URL. A newer value cancels a read still running. Read in the browser by the dependency-free reader; nothing is uploaded.
`workbook`	`OgeWorkbook \| null`	`null`	A workbook built or read elsewhere; wins over `source` when both change.
`locale`	`string \| undefined`	`undefined`	BCP 47 locale of the built-in number formats, separators and month names — Excel takes them from the reader's region. Default: the configured locale, else the browser's.
`messages`	`Partial<OgeSpreadsheetMessages>`	`{}`	Per-instance overrides of the message catalog, merged over the configured one. Every user-facing string lives there — aria labels and live-region announcements included.

Chrome

Name	Type	Default	Description
`showFormulaBar`	`boolean`	`true`	The name box (type a reference or a defined name, Enter goes there) and the read-only formula bar (a dynamic array's followers show the anchor's formula in grey).
`showSheetTabs`	`boolean \| undefined`	`undefined`	The sheet tabs, with tab colours. Default: the workbook's own setting.
`showStatusBar`	`boolean`	`true`	The status bar: the selection's Average, Count and Sum in the active cell's number format (Excel's rules), and the zoom slider.
`showHeaders`	`boolean \| undefined`	`undefined`	Row and column headers. Default: each sheet's own setting.
`showGridLines`	`boolean \| undefined`	`undefined`	Gridlines. Default: each sheet's own setting.

State (two-way)

Name	Type	Default	Description
`activeSheet`	`model<number \| undefined>`	`undefined`	The active sheet's index. A value set before the workbook opens is held until it does, and wins over the file's own active sheet; hidden sheets are refused. Each sheet keeps its selection, zoom and scroll position.
`zoom`	`model<number \| undefined>`	`undefined`	The active sheet's zoom in percent (10–400); each sheet keeps its own. Geometry stays in whole pixels per row and column, as Excel draws it.

Controller

Name	Type	Default	Description
`core`	`OgeSpreadsheetCore`	—	The framework-free controller from `@oge-ui/spreadsheet-engine` (ADR 0003) — selection, keyboard map, find, copy, the grid frame, pointer gestures and announcements. The React viewer runs the same class.

Methods 9

Methods

Name	Type	Description
`open(source)`	`(source: OgeSpreadsheetSource) => Promise<void>`	Opens a workbook; resolves once it is shown (or failed) and `loaded` / `loadError` fired.
`getWorkbook()`	`() => OgeWorkbook \| null`	The open workbook.
`selectSheet(index)`	`(index: number) => boolean`	Shows a sheet; `false` for a hidden or missing one.
`goTo(reference)`	`(reference: string) => boolean`	Goes to `B4`, `Sheet2!A1:C3`, `C:C`, `3:3` or a defined name — as the name box does; `false` when unknown.
`setZoom(percent)`	`(percent: number) => void`	Sets the zoom (clamped to 10–400%).
`find(query, options?)`	`(query: string, options?: OgeFindOptions) => void`	Opens the find bar on `query` and selects the first match after the active cell.
`copy()`	`() => Promise<boolean>`	Copies the active range through the async clipboard API: what the cells show as text, plus Excel-compatible HTML. A whole row or column copies its used part.
`print()`	`() => void`	Prints the active sheet's used range as a table (the sheet's page setup decides the gridlines) from a hidden frame built node by node, never from markup.
`focus()`	`() => void`	Focuses the grid.

Events 5

Events

Name	Type	Description
`loaded`	`OgeSpreadsheetLoadedEvent`	A workbook opened from `source` or `open()`.
`loadError`	`OgeSpreadsheetLoadErrorEvent`	Opening failed; the placeholder shows the error's message.
`selectionChange`	`OgeSpreadsheetSelectionChangeEvent`	The selection changed — keys, pointer, find, go to, a sheet switch.
`hyperlinkClick`	`OgeSpreadsheetHyperlinkClickEvent`	An external link is about to open (a click, or Alt+Enter); cancelable. It opens in a new browsing context without an opener.
`cellClick`	`OgeSpreadsheetCellClickEvent`	A cell was clicked.

Types 23

Types

Name	Type	Description
`OgeSpreadsheetSource`	`ArrayBuffer \| Uint8Array \| Blob \| string`	What the viewer opens: the workbook's bytes, a `Blob` / `File`, or a URL it fetches with same-origin credentials. A URL that cannot be fetched fails with `fetch-failed`.
`OgeSpreadsheetLoadedEvent`	`interface`	`{ workbook, issues }` — the open `OgeWorkbook` and what the reader could not show as Excel does, aggregated per code and place.
`OgeSpreadsheetLoadErrorEvent`	`interface`	`{ error }` — an `OgeXlsxError`.
`OgeSpreadsheetSelectionChangeEvent`	`interface`	`{ sheet, ranges, active, address }` — the active sheet's index, the selected ranges (zero-based, inclusive), the active cell and its address (`B4`).
`OgeSpreadsheetHyperlinkClickEvent`	`interface`	`{ href, link, cancel }` — an external link about to open (the target is sanitised; `javascript:` and friends never reach it). Set `cancel = true` to open it yourself, or not at all. Internal links (`Sheet2!A1`, a defined name) navigate without the event.
`OgeSpreadsheetCellClickEvent`	`interface`	`{ row, col, address, text, event }` — a click: down and up on one cell without a drag. `text` is what the cell shows.
`OgeFindOptions`	`interface`	`{ matchCase?, entireCell?, formulas?, workbook? }` — Excel's Find options: case, the whole cell, formulas instead of what cells show, every visible sheet. Queries take Excel's `*` and `?` wildcards (`~` escapes them).
`OgeImportIssue`	`interface`	`{ code, severity, count, sheet?, part?, ref?, detail? }` — one kind of thing shown differently from Excel (or kept without being shown), counted per sheet and part; `ref` is the first occurrence, `detail` an English note for logs.
`OgeImportIssueCode`	`string union`	What the reader reports, e.g. `'macros-kept'` (a `vbaProject.bin` is kept and never run — the viewer shows a message bar), `'drawing-not-shown'` (charts and shapes, kept for saving), `'uncalculated-formulas'`, `'external-link'` (kept, never fetched), `'truncated'`, `'strict-conformance'`.
`OgeWorkbook`	`class`	The engine's workbook model (`@oge-ui/spreadsheet-engine`): sheets, styles, names, opaque parts. Build one in code and pass it to `workbook`, or read it from `loaded`.
`OgeXlsxError`	`class`	Why a file could not be read: `code` is `'not-xlsx'`, `'encrypted-or-legacy'` (a password-protected workbook or an old `.xls`), `'xlsb'`, `'corrupt'`, `'too-large'`, `'aborted'` or `'fetch-failed'`.

Keyboard

Name	Type	Description
`Arrows / Ctrl+arrows / Shift`	`move`	Move the active cell over hidden rows, hidden columns and merges; Ctrl jumps to the data edge as `Range.End` does; Shift extends from the anchor.
`Home / Ctrl+Home / Ctrl+End / Page Up / Page Down / Alt+Page`	`move`	Start of the row, the first cell below the frozen panes, the last used cell, a screen up or down, a screen sideways.
`Tab / Enter (Shift)`	`move`	Step right / down — inside a multi-cell selection they cycle within it.
`Shift+Space / Ctrl+Space / Ctrl+A / Shift+F8`	`select`	Whole rows, whole columns, the current region then everything, add mode (arrows move, clicks add ranges).
`Ctrl+C / Ctrl+F / F5 or Ctrl+G / Shift+F2 / Alt+Enter`	`act`	Copy as text and Excel HTML, find, go to (the name box), show the active cell's note, open its link.
`Ctrl+Page Up / Ctrl+Page Down / Ctrl+= / Ctrl+− / Ctrl+wheel`	`view`	Previous / next sheet, zoom in and out on Excel's steps.
`Escape`	`close`	Closes the find bar, add mode or an open note — and when nothing is open the key stays the page's (a dialog around the viewer still closes).

Configuration

Name	Type	Description
`provideOgeSpreadsheetConfig(config)`	`(config: OgeSpreadsheetConfigInput \| (() => OgeSpreadsheetConfigInput)) => Provider`	DI-level configuration for every viewer below: `messages` (merged over the defaults) and `locale`. A function makes it live — viewers re-render when a signal it reads changes, e.g. switching the UI language.
`OGE_SPREADSHEET_CONFIG`	`InjectionToken<OgeSpreadsheetConfig>`	The token behind the provider; injects the resolved config.
`OGE_DEFAULT_SPREADSHEET_CONFIG / OGE_DEFAULT_SPREADSHEET_MESSAGES`	`OgeSpreadsheetConfig / OgeSpreadsheetMessages`	The English defaults a partial config or catalog merges over (from the engine, shared with React).
`OgeSpreadsheetConfig / OgeSpreadsheetConfigInput`	`interface`	`{ messages, locale? }`; the input takes every field optionally and `messages` partially.
`OgeSpreadsheetMessages`	`interface`	Every user-facing string, as templates with `{name}` placeholders and ICU plurals (filled by `ogeFormatMessage` in the viewer's locale): grid, tab, name box, formula bar and status bar labels, the find bar, the placeholders, the `errors` and `issues` blocks (one text per error and import-issue code), and the live-region announcements (`cellAnnouncement`, `selectionAnnouncement`, `sheetAnnouncement`, `copied`, `zoomLabel`, …). A partial override replaces a nested block whole; `@oge-ui/locales` ships translated packs (`ogeMergeMessages(OGE_DEFAULT_SPREADSHEET_MESSAGES, tr.spreadsheet)`).

Notes

The grid is a role="grid" whose active cell is its aria-activedescendant: a screen reader hears the address, what the cell shows, its formula, a merge, a link and a note as you move. Range selections, sheet switches, copying, zooming and find results are announced through a polite live region; the sheet tabs are a role="tablist" with one Tab stop.
What you see is measured, not approximated: column widths and row heights come from Excel's own font metrics, text fitting and number formats from thousands of samples captured on a real Excel, and borders, fills, gridlines and the selection were diffed against Excel's screen pixel by pixel.
Macros are kept and never run; the viewer says so in a message bar. Charts and shapes are kept for saving but not drawn yet — the loaded event's issues lists everything shown differently from Excel.
Pictures are shown from blob: URLs and the cells' pattern fills from data: SVGs: a strict CSP needs img-src 'self' data: blob:.