API reference

This reference is generated from the source and describes the API as it stands today. It is not published as a package yet; see For developers.

Start

There is one entry point, src/api/index.js.

import { createWorkbook, mountWorkbook } from './src/api/index.js';

// No page needed; this also runs in Node.
const wb = createWorkbook({ sheets: 2 });
const sheet = wb.activeSheet;
sheet.range('A1').values = [['Item', 'Qty'], ['Pens', 4]];
sheet.range('C2').formulas = [['=B2*2']];
sheet.range('A1:B1').style = { bold: true, fill: { theme: 'accent1' } };
await wb.whenCalculated();

// The full app in any element, which needs a height.
const onPage = await mountWorkbook(document.querySelector('#here'), { chrome: 'light' });

Several workbooks can share a page, as src/api/dev/demo.html shows. A page event such as paste reaches the workbook last clicked or focused.

Choosing parts

The full app is one composition of parts. Each part in parts is true, false, or an element to place it in.

await mountWorkbook(el, {
  parts: { titleBar: false, ribbon: false, formulaBar: true, nameBox: false, tabStrip: true, statusBar: myFooter, sidePanels: false },
});

A left-out ribbon doesn't load: context menus use a small menu class instead. The other code loads on the first mount whichever parts you choose, because the file code of charts, slicers, pivots and data sheets is needed to open and save a file.

Fast bulk paths

range.values takes plain arrays. For large data, these write typed arrays straight into cell storage:

sheet.range('A1').setNumbers([new Float64Array(1e6), new Float64Array(1e6)]);   // one array per column; NaN is an empty cell
sheet.range('C1').setStrings(['a', 'b', null]);
sheet.range('D1').setStyleIds(new Uint16Array(1e6).fill(wb.styleId({ bold: true })));
const column = sheet.range('A:A').numbers();

Pass { undoable: false } when loading fresh data, to skip the undo copy. Bulk writes fire bulk-written and, when undoable, cells-changed with bounds instead of a cell list. A bulk write over a table header doesn't rename the column; values under 4,096 cells does.

Events

const off = wb.events.on('cells-changed', (e) => {
  for (const { row, col } of e.cells()) console.log(row, col);
});
wb.events.on('before-sheet-remove', (e) => e.cancel());

A group's hooks exist only while a listener of that group does. With none, the app runs its own methods with nothing in between.

Undo

wb.history.transaction('Import', () => {
  sheet.range('A1').values = rows;
  sheet.range('A:A').style = { bold: true };
});
wb.history.undo();

Commands and shortcuts

wb.commands.register('app.stamp', {
  label: 'Stamp',
  keys: 'mod+shift+k',
  execute: (ctx) => { ctx.range.values = [[new Date()]]; },
});
wb.commands.execute('format.bold');
wb.commands.bindKey('mod+k', 'app.stamp');
wb.commands.disableKey('arrowup');

mod means Cmd or Ctrl. Edits a command makes become one undo step. A command that changes something outside the model gives undo too. On a mounted workbook every action of the app's key table is also available as grid.<name>.

Saving

CallResultKeeps
wb.toJSON()plain dataThe whole model. Pivot definitions, data sheet sources and picture bytes aren't included; warnings lists what's left out.
wb.saveDocument(handle)a .8sh file, or a Blob with no handleEverything, including what Excel can't hold.
wb.saveXlsx(sink)an xlsx fileWhat Excel holds. Features with no Excel form go in customXml parts.

Reading SpreadJS's own .sjs and ssjson files is out of scope, because that format isn't documented for third parties.

The .8sh format is a ZIP: manifest.json, model.json, then either one binary entry per cell chunk or, for a workbook that came from a file or has pivots or data sheets, package.xlsx holding everything Excel can hold. In a browser, the ZIP work runs in a Worker one entry at a time, with an acknowledgement after each.

Themes

wb.theme.apply('Facet');
wb.theme.setColors('Blue Warm');
wb.theme.setFonts({ major: 'Georgia', minor: 'Verdana' });
wb.theme.apply(wb.theme.build({ name: 'Ours', colors: { accent1: '#123456' } }));
sheet.range('A1').style = { color: { theme: 'dk2' }, fill: { theme: 'accent1', tint: 0.4 } };
wb.theme.chrome = 'dark';                 // or light, auto
wb.theme.chrome = 'colorful';             // or white, light-gray, dark-gray, black, slate
wb.theme.chrome = { base: 'light', tokens: { chrome: '#eef' }, grid: { headerBg: '#ddf' }, titleBar: { background: '#225', color: '#fff' } };

A color given as { theme, tint } follows the theme here and in Excel. xl/theme/theme1.xml is written when a theme was applied.

Interface language

const wb = await mountWorkbook(el, { language: 'pl' });   // or 'en'; left out, the user's choice or the browser's
wb.language = 'en';                                       // the ribbon, menus and status bar switch at once
await wb.setLanguage('pl');                               // resolves once the app shows it

The language is the page's, so workbooks on one page share it. It is apart from the region, which sets how numbers, dates and formula separators read, as in Excel. Catalogs are in src/i18n; tools/i18n-check.mjs checks them.

Reference

Workbook

MemberWhat it does
book (read)The core workbook. Its shape isn't part of the public API.
commands (read)Named commands and shortcuts.
users (read)Who is using the workbook, and who is editing what.
usersIfAny (read)The user directory, if anything has used it.
theme (read)The workbook theme.
names (read)Defined names.
printDefaults (read)Default paper and units for this workbook.
menus (read)Context menu customization. Only a mounted workbook has one.
ribbon (read)Ribbon extensions. Only a mounted workbook has one.
sheets (read)Every sheet in workbook order.
sheet(which)A sheet by name or position.
activeSheet (read and write)The sheet the user sees. Shows a sheet.
addSheet(name)Adds a sheet at the end and shows it.
removeSheet(which)Deletes a sheet. The last visible sheet can't go.
moveSheet(which, to)Moves a sheet to a position.
duplicateSheet(which)Copies a sheet.
renameSheet(which, name)Renames a sheet and rewrites references to it.
getSelection()The selection of the active sheet.
addSelection(sheet, range)Adds a range to the selection. Only a mounted workbook has a selection on screen.
clearSelection(sheet)Back to just the active cell.
showCell(row, col, { vertical = 'nearest', horizontal = 'nearest' } = {})Scrolls so that a row and column show. vertical: 'nearest', 'top', 'center' or 'bottom'; horizontal: 'nearest', 'left', 'center' or 'right'. Does nothing without a page.
viewport (read)What shows now: { top, bottom, left, right }, or null without a page.
setSelection(sheet, selection)
editorStatus (read)The cell editor's state: ready, enter or edit. A workbook with no page is always ready.
selectedRanges (read)Selected ranges as handles.
setZoom(sheet, value)
hitTest(x, y)What is at a point, in CSS pixels relative to the mounted element.
getCellRect(row, col)A cell's rectangle in CSS pixels relative to the mounted element.
withSheet(raw, fn)Runs fn with raw as the active sheet, because core edits act on the active sheet.
readCell(raw, r, c)The value of a cell, calculating it first if it's waiting.
normalizeStyle(patch)Stored style patch from a public one.
styleId(patch, base = 0)The id of a style built from a patch, for setStyleIds. [base]: the style to start from.
touched(reason = 'cells')Marks the workbook edited and repaints.
axisEdit(sheet, axisName, from, to, change)One undoable change to row or column sizes.
structure(sheet, op)One undoable insert or delete of rows or columns.
calculate()Recalculates now, also in manual mode.
whenCalculated()Resolves when all formulas are current.
calculationMode (read)auto or manual.
language (read and write)The interface language of the ribbon, menus, dialogs and messages: en or pl. Every workbook on a page shares it; the region is apart. Switches it: the ribbon, menus and status bar follow at once, and open dialogs keep theirs until reopened.
setLanguage(code)Switches the interface language and resolves to the code in use once the app shows it. An unknown code changes nothing.
customData (read)Your own data, stored in JSON and .8sh documents, but not in xlsx. Must be plain data.
toJSON(options = {})The whole model as JSON-ready data, following the published schema. [options]: styles: false and formulas: false make a values-only copy.
fromJSON(data, options = {})Replaces the workbook's contents with toJSON output. This clears undo. [options]: recalculate: true ignores cached values.
async saveDocument(target = null, options = {})Saves as a .8sh document, which keeps everything, including what Excel can't hold. [target]: a file handle, or any object with async write. Null returns a Blob.
async openDocument(blob, options = {})Opens a .8sh document, replacing the workbook's contents. This clears undo.
async saveXlsx(sink)Saves as xlsx through the same writer as the app.
async openFile(file)Opens an xlsx or csv file. Only a mounted workbook can, because reading runs in its Worker.
async rangeToHtml(ref, options)Text of the range as a table. See export-html.js.
destroy()Removes the workbook from the page and releases its listeners.

Sheet

MemberWhat it does
name (write)Renames the sheet and rewrites formulas that refer to it.
index (read)Position in workbook order.
range(ref, col, row2, col2)A range from A1 text, a box, or row and column numbers.
cell(row, col)One cell by zero-based row and column.
usedRange (read)The cells that hold anything. Null on an empty sheet.
freeze(rows, cols = 0)Keeps rows and columns visible while scrolling.
zoom (write)Zoom factor, 0.1 to 4.
rowHeight(row)
colWidth(col)
setRowHeight(from, to, size)Sets row heights as one undoable step.
setColWidth(from, to, size)Sets column widths as one undoable step.
rowResizable(row)Whether a row or column can be sized by dragging.
setRowResizable(row, on = true)Makes a row fixed, or resizable again. It still follows code and the size dialogs.
rowLimit (read)How many rows and columns this sheet has.
setRowLimit(count, { keepData = false } = {})Sets how many rows the sheet has. Rows past the limit are deleted, with their data, unless keepData is true and there is data there, when nothing changes. Excel's sheets stay full size.
hideRows(from, to, hidden = true)Hides or shows rows.
hideCols(from, to, hidden = true)Hides or shows columns.
insertRows(at, count = 1)Inserts rows above at. References in every sheet adjust.
deleteRows(at, count = 1)Deletes rows from at.
insertCols(at, count = 1)Inserts columns before at.
deleteCols(at, count = 1)Deletes columns from at.
clearFilter()Removes AutoFilter from this sheet and shows its hidden rows.
tables (read)Tables on this sheet.
addTable(range, options = {})Makes a table from a range.
charts (read)Charts on this sheet.
shapes (read)Shapes, connectors, pictures and text boxes on this sheet.
addChart(type, range, rect)Adds a chart. type: a chart type such as column, line or pie; [range]: the data; a single cell uses the block of data around it; [rect]: position in points.
addShape(kind, rect)Adds a shape. kind: a DrawingML preset such as rect or ellipse, or line, arrow.
addCustomShape(model, options)Adds a shape whose outline comes from formulas that can read cells. model: adjust, guides, paths, handles, sites, textBox; see src/shapes/README.md.
addNote(cell, text, author)Adds a note. [author]: defaults to the current user's name.
addValidation(rule)Adds a data validation rule. Fields follow the file format, for example { sqref: 'B2:B9', type: 'list', formula1: '"a,b"' }.
addConditionalFormat(block)Adds conditional formatting. Fields follow the file format, for example { sqref: 'C2:C9', rules: [{ type: 'cellIs', operator: 'greaterThan', dxfId: 0, priority: 1, formulas: ['5'] }] }.
protect(options = {})Protects the sheet. Pass the file format's option names to allow actions.
unprotect()Removes sheet protection.
print (read)Page setup, page information, preview lines and watermark of this sheet.

Range

MemberWhat it does
address (read)A1 text of this range.
usedBox()
offset(rows = 0, cols = 0, rowCount = this.rowCount, colCount = this.colCount)
values (read and write)Cell values by row: numbers, strings, booleans, and null for empty cells. Errors read as their text, such as #N/A. Writes values. An array of arrays starts at the top-left cell. One value fills the range. Text is stored as text: nothing here parses it, so =1+1 stays a string. Use formulas or input for parsing.
usedOrWhole()The range to fill for a scalar write: whole rows and columns stop at the used range.
input(data)Writes text as if typed: numbers, dates, percentages, booleans and formulas are parsed under Excel's entry rules.
formulas (read and write)Formulas by row, as the user sees them with a leading =. Cells without a formula read as null. Writes formulas with or without a leading =. Null clears the cell. One string goes to every cell, with its relative references adjusted as a fill would.
setNumbers(columns, options = {})Fastest way in: writes one typed array per column, starting at the top-left cell, by memcpy into chunks. NaN writes an empty cell. [options]: undoable: false skips the undo copy when loading fresh data.
setStrings(columns, options = {})Writes one array of strings per column, through the string table.
numbers(x = 0)Reads one column as a Float64Array in one pass per chunk. Cells that aren't numbers read as NaN. [x]: column offset inside the range.
style (read and write)The effective style of the top-left cell, as a plain object. Applies a partial style to the range. Whole rows and columns cost one record each, not one per cell.
altText (read and write)Alternative text of the top-left cell: what a screen reader says instead of the shown text, with {value} standing for that text. Null when there's none. Sets the alternative text of every cell in the range, as one undo step; '' or null removes it.
styleIds(x = 0)Style ids of one column as a Uint16Array, for reuse with setStyleIds. [x]: column offset inside the range.
setStyleIds(columns, options = {})Writes style ids per column by memcpy. Get an id from workbook.styleId(patch).
clear(what = 'contents')Clears the range. contents keeps formats; all removes both.
merge(options = {})Merges the range. Excel keeps only the first value.
unmerge()Removes merged cells in the range.
sort(keys, options = {})Sorts rows of the range in place. Undo is a pointer swap. [options]: headers: true leaves the first row where it is. ignoreHidden: false moves hidden rows too. A key's compare is a function or a name given to registerSortCompare..
filter(columns = {})Turns on AutoFilter for this range, whose first row holds the headers, and optionally filters it. [columns]: for each column index or letter, the display values to keep.
currentRegion()
select()Makes this the selection of a mounted workbook; a headless one just remembers it.

Table

MemberWhat it does
name (write)Renames the table and rewrites structured references.
resize(range)Moves the table's edges.
setOption(key, value)Turns on or off the header row, totals row, or a stripe option.
remove()Turns the table into ordinary cells.

Names

MemberWhat it does
list()
get(name, sheet)
set(name, refersTo, options = {})Adds or changes a name as one undoable step. refersTo: for example Sheet1!$A$1:$B$9, with no leading =; [options]: a sheet makes the name local to it.
remove(name, options = {})Removes a name as one undoable step.

History

MemberWhat it does
canUndo (read)
canRedo (read)
undo()Undoes the last step.
redo()Redoes the last undone step.
clear()Empties both stacks.
undoEntries (read)Oldest first: { label, user, cells, sheet }, for an undo menu.
redoEntries (read)Oldest first, as undoEntries.
jumpTo(undoDepth)Undoes or redoes until the stack has undoDepth entries, for a history dropdown.
limit (read)Most steps kept. 0 turns undo off.
bookChanged()Called when the host replaces the book.
begin(label = 'transaction')Opens a transaction: every edit until commit becomes one undo step. For synchronous work, transaction is simpler.
commit()Folds the edits since begin into one step.
rollback()Undoes the edits since begin and drops them, with no undo step left behind.
transaction(label, fn)Runs fn as one undo step. If it throws, its edits are undone and the error passes on. fn: must be synchronous; use begin and commit around asynchronous work.
silently(fn)Runs fn with its edits left off the stacks: the body of a custom command's undo.

Commands

MemberWhat it does
register(name, spec)Adds a command, or replaces one with the same name.
unregister(name)Removes a command and its shortcuts.
has(name)
list()Every command name with its label and whether it leaves an undo step.
context()The state a command runs against.
execute(name, args)Runs a command by name. Edits it makes become one undo step named after it.
bindKey(combo, name, options = {})Binds a key to a command. It takes priority over the grid's own use of that key. combo: for example mod+shift+k, f9, enter; [options]: inEditor also fires while a cell is being edited.
unbindKey(combo)Removes a binding made with bindKey. A built-in shortcut on that key works again.
disableKey(combo)Turns a key off, including a built-in shortcut. The key then does nothing in the grid.
keymap()The effective shortcuts: combo to command name, null for disabled keys.
handleKey(e, editing = false)Runs the binding for a keyboard event.

Events hub

MemberWhat it does
has(type)True when type has a listener. Feed sites check this before building an event.
on(type, fn, options = {})Adds a listener. type: a name from the event catalog.
off(type, fn)Removes one listener, or all listeners of a type when fn is omitted.
emit(type, fields = {})Fires an event.
dispatch(type, fields = {})Like emit, but hands back the event, so a feed site can read fields a listener set.
size (read)Number of listeners across all types.

Users

MemberWhat it does
current (read and write)The current user. With none set, it is a built-in Guest. Sets the current user, by id or by a user object to add. New comments and undo steps carry this user.
add(...users)Adds users to the directory, and makes each available to threaded comments.
connect(source)Connects your own user store. get loads one user; search finds users by name or email.
async get(id)A user by id, from the directory or your store.
async search(query)Users whose name or email contains the text.
setPresence(userId, where)Publishes where a user is. A mounted workbook draws an outline with the user's name. Pass null when the user leaves. Moving presence between machines is up to your transport.
editors (read)Everyone with published presence, including what they are editing.

Themes

MemberWhat it does
gallery (read)Themes of the gallery.
colorSets (read)Named color sets.
fontSets (read)Named font pairs.
current (read)The theme in use.
apply(theme)Applies a theme as one undoable step. Cell styles that follow the theme, charts and tables change with it. theme: a gallery name, or a theme from build.
setColors(colors)Changes only the colors, from a color set name or a slot map.
setFonts(fonts)Changes only the fonts, from a font set name or a pair.
build(spec)Builds a custom theme from partial input and checks it. It isn't applied until you call apply.
fromXml(xml)Loads a theme from theme XML, such as a theme1.xml you extracted.
toXml()The XML the workbook saves as xl/theme/theme1.xml.
chrome (read and write)The chrome around the cells. auto follows the system. Cells stay white, as in Excel. A headless workbook only stores it.
skins (read)Named chrome skins: Excel's white, light and dark gray, colorful and black looks, and a slate one.
restore(data)Puts a saved theme back with no undo step and no style change: the styles in the data are already resolved.

Printing of a sheet

MemberWhat it does
setup (read)Page setup, as plain data. Change it through set.
set(patch)Changes page setup. Margins given here use the default units. patch: fields of page setup, such as orientation, scale, fitToPage, gridLines, margins, printAreas.
pageInfo(options = {})Which cells land on which printed page. [options]: a window of pages, for very long sheets.
previewLines (read)Whether dashed preview lines show where pages break.
watermark (read and write)The image printed behind this sheet's cells, or null. Sets the watermark. It prints on every page and shows faintly on the grid.
async toPdf(sink, options = {})Writes this sheet as a PDF. [options]: passed to the PDF writer, for example title and fonts.
MemberWhat it does
paperSizes (read)Paper sizes by xlsx code, with their sizes in points.
marginPresets (read)Named margin presets, in inches.
toUnits(inches)Converts inches, which page setup stores, to the default units.
fromUnits(value)Converts a value in the default units to inches.

Options

MemberWhat it does
applyAll()Applies every option that differs from its default. Called once after mounting.
bookChanged()A new book came in: settings kept on the book go on it again.
get(key)The value of an option.
set(patch)Changes options after mounting.
list()Every option with its value.

Context menus

MemberWhat it does
add(item)Adds an item.
remove(id)Removes an added item, or hides a built-in one by id, such as cut or clear-contents.
restore(id)Shows a built-in item again.
filter(fn)Adds a function that edits the list right before it shows.
setRenderer(fn)Replaces how menus draw. Return true when you have shown the menu yourself.
install()Installs the hook. The bridge calls this while the menu group is active.

Ribbon

MemberWhat it does
addTab(tab)Adds a tab after the built-in ones.
removeTab(name)Removes a tab you added.
addGroup(tabName, group)Adds a group at the end of any tab, including a built-in one such as Home.

Status bar

MemberWhat it does
add(item)Adds your own item, or replaces one with the same id.
remove(id)Removes an item.
setVisible(id, on)Shows or hides an item by id: average, count, numericCount, min, max, sum, or your own.
setZoomVisible(slider, percent = slider)Shows or hides the zoom slider and the zoom percentage.
setMessage(text)Puts a message in the bar's left part. It returns to Ready after a few seconds.
refresh()Redraws the statistics.

Name box

MemberWhat it does
entries()Every name and table the list shows, then the active sheet's objects.
go(text, options = {})Goes to a name, table, object or range. With allowCreate, an unknown name is defined for the selection, as typing in the box does.
setListVisible(on)Shows or hides the list button.

All events

Every event object has type, workbook, cancelled and cancel().

Cells and structure

EventCancelNeeds a pageFieldsWhen
before-changeyeslabel, sheetAn undoable edit is about to run.
cells-changedsheet, label, reason, count, bounds, cells()Cells changed through any path: typing, paste, fill, API, undo or redo. cells() lists them lazily.
step-donesheet, label, reasonAny undoable step finished or was undone or redone, including ones that touch no cell, such as a format or a theme.
bulk-writtensheet, bounds, countA typed-array bulk write finished. It reports bounds instead of cells.
before-structureyessheet, labelRows or columns are about to be inserted or deleted.
structure-changedsheet, label, reasonRows or columns were inserted or deleted.
before-sortyessheetA sort is about to run.
range-sortingsheet, range, infoA sort is working out its order; set info.compareFunction to compare two cell values your own way.
sortedsheet, reasonA sort finished.
before-filteryessheetA filter is about to change, from the API or a filter menu.
filteredsheet, reasonA filter was applied or cleared.
invalid-operationaction, reasonAn action was refused, for example by protection or a listener.

Selection

EventCancelNeeds a pageFieldsWhen
before-selectionyesyessheet, from, toThe selection is about to change.
selection-changedyessheet, from, toThe selection changed.
cell-enteryessheet, row, colThe active cell moved onto a cell.
cell-leaveyessheet, row, colThe active cell left a cell.

Pointer

EventCancelNeeds a pageFieldsWhen
cell-clickyessheet, hit, originalEventA click landed on a cell or header. The hit test is included.
cell-double-clickyesyessheet, hit, originalEventA double click landed on the grid. Cancelling stops the edit it would start.
tab-clickyessheet, indexA sheet tab was clicked.
tab-double-clickyessheet, indexA sheet tab was double clicked.

Editing

EventCancelNeeds a pageFieldsWhen
before-edityesyessheet, row, col, initial, originA cell editor is about to open.
edit-startedyessheet, row, col, text, originThe cell editor opened.
edit-inputyessheet, row, col, textThe text in the editor changed.
before-commityesyessheet, row, col, textThe editor is about to store its text. Set text to replace it; cancelling keeps the editor open.
edit-endedyessheet, row, col, committedThe editor closed.
editor-statusyesfrom, toEditor status moved between ready, enter and edit.
validation-failedyessheet, row, col, text, ruleText entered in the editor breaks the cell's data validation rule.

comments

EventCancelNeeds a pageFieldsWhen
before-comment-changeyessheetA threaded comment is about to change.
comment-changedsheetA threaded comment changed.
before-mentionyesqueryThe list of people to mention is about to open. Cancel it and @ stays plain text.
mentionedpersonA person was mentioned.

Clipboard

EventCancelNeeds a pageFieldsWhen
before-copyyesyessheet, ranges, cutCopy or cut is about to run.
after-copyyessheet, ranges, cutCopy or cut finished.
before-pasteyesyessheet, ranges, textPaste is about to run. text is the plain text on the clipboard.
after-pasteyessheet, ranges, textPaste finished.

Sheets

EventCancelNeeds a pageFieldsWhen
before-active-sheetyesfrom, toThe active sheet is about to change.
active-sheet-changedfrom, toThe active sheet changed.
sheet-addedsheetA sheet was added or duplicated.
before-sheet-removeyessheetA sheet is about to be deleted.
sheet-removednameA sheet was deleted.
before-sheet-renameyessheet, from, toA sheet is about to be renamed.
sheet-renamedsheet, from, toA sheet was renamed.
before-sheet-moveyessheet, from, toA sheet is about to move.
sheet-movedsheet, from, toA sheet moved.

Rows and columns

EventCancelNeeds a pageFieldsWhen
axis-resizedsheet, axis, indexesRow or column sizes or hidden state changed.

drag

EventCancelNeeds a pageFieldsWhen
before-fillyesyessheet, from, to, modeA fill drag is about to write its cells.
filledyessheet, from, to, modeA fill drag finished.
before-drag-mergeyesyessheet, rangeA drag on the merge grip is about to merge cells.
drag-mergedyessheet, rangeA drag on the merge grip merged cells.
before-moveyesyessheet, dragDragging the selection border is about to move or copy cells.
cells-movedyessheet, dragA drag moved or copied cells.

Calculation

EventCancelNeeds a pageFieldsWhen
calc-progressremaining, totalA calculation slice finished on a large workbook.
calc-endCalculation finished and all values are current.

View

EventCancelNeeds a pageFieldsWhen
before-zoomyesyesfrom, zoomThe zoom is about to change. Set zoom to clamp it, or cancel.
view-changedyeszoomThe zoom changed.
scrolledyesx, y, topRow, leftColThe grid scrolled.

Objects

EventCancelNeeds a pageFieldsWhen
object-selectedyesobjectThe selected chart, shape or picture changed.
EventCancelNeeds a pageFieldsWhen
menu-openingyesyesarea, items, x, y, hitA context menu is about to open. items can be edited in place.

Workbook

EventCancelNeeds a pageFieldsWhen
command-executedname, args, resultA named command ran.
before-printyessheetsA print or PDF job started through the API is about to run.
theme-changedthemeThe workbook theme changed.
user-changeduserThe current user changed.
presence-changeduserId, presenceSomeone started or stopped editing a range.
workbook-loadedsourceA JSON model or document replaced the workbook contents.

All options

Give them to mountWorkbook, or change them later with wb.settings.set({ ... }). src/api/dev/options-check.mjs checks each one by what it does on a mounted workbook.

OptionDefaultWhat it does
sheets1Number of sheets a new workbook starts with.
defaultFontnullDefault font, such as { name: "Arial", size: 11 }.
dragMergefalseMerge cells by dragging the grip on the selection.
dragHeaders"none"Move rows or columns by dragging their selected headers: none, row, col, both.
dragDroptrueMove cells by dragging the selection border.
dragFilltrueFill by dragging the corner handle.
fillDefault"auto"What a fill drag does by default: auto, copy, series, formats, values.
fillSmartTagtrueShow the options button after a fill drag.
userZoomtrueZoom with the pinch gesture and the status bar slider.
userResizetrueResize rows and columns by dragging their header edges.
undotrueKeep an undo history. False empties it and stops it growing.
contextMenutrueShow the right-click menu.
deselecttrueCmd or Ctrl and a click on a selected cell takes it out of the selection.
touchLayoutfalseLarger touch targets.
hideSelectionfalseHide the selection while the workbook has no focus.
zeroSizeMark"none"Mark rows and columns of size zero in the headers: none or lines.
scrollbarVtrueShow the vertical scroll bar: true, false or auto.
scrollbarHtrueShow the horizontal scroll bar: true, false or auto.
scrollToMaxfalseSize the scroll bars on the whole sheet instead of the used range.
scrollAlignMaxfalseStop scrolling with the last row and column at the viewport edge.
scrollbarStyle"overlay"Scroll bar look: overlay as on macOS, skin always on, mobile thin.
scrollTip"both"Show the row or column while dragging a scroll bar: none, row, col, both.
scrollSkipsHiddentrueHidden rows and columns take no room on the scroll bars. False gives them their room, so the thumb shows their position.
pixelScrolltrueScroll by pixel. False scrolls by whole rows and columns.
scrollStep1Multiplies the distance of one wheel notch.
tabStriptrueShow the sheet tabs.
tabStripShare0.6Share of the width the tab strip takes beside the horizontal scroll bar, from 0 to 1.
renameTabstrueRename a sheet by double clicking its tab.
reorderSheetstrueMove sheets by dragging their tabs.
newSheetButtontrueShow the new-sheet button.
sheetNavButtonstrueShow the previous and next sheet buttons.
allSheetsList"auto"Show the button that lists all sheets: auto, true or false.
tabStylesnullDefault look of sheet tabs: { color, background, activeColor, activeBackground, font }.
copyIndicatortrueShow the moving border around copied cells.
copyIndicatorColornullColor of that border.
pasteExcelStylestrueKeep the look of a table pasted from Excel or a web page. False pastes its text.
pasteExtendstruePaste everything when the data is larger than a multi-cell selection. False stops at the selection.
pasteHeaders"none"Add header text to what is copied: none, rows, cols, both. Other apps get it with the cells.
pasteSkipsHiddenfalseSkip hidden rows and columns when pasting.
backgroundnullBackground color of the cell area.
backgroundImagenullPicture behind the cells of every sheet, as a data URL. It saves as Excel's sheet background.
backgroundImageFit"tile"How that picture fits: tile, as Excel draws it, center, stretch, zoom.
emptyAreaColornullColor beyond the last row and column, which shows when scrolled to the sheet's end.
resizeTip"both"Show the size while resizing: none, row, col, both.
dragFillTiptrueShow the fill value while dragging.
dragDropTiptrueShow the target while dragging cells.
flagInvalidDatafalseCircle cells that break their validation rule. Costs only while on, and only for visible cells.
editFormulastrueLet the user enter and edit formulas in cells. False keeps formulas as they are and takes typed = as text.
formulaBoxtrueShow function lists and argument hints while typing a formula.
formulaHinttrueA formula in a General cell takes a format from what it calculates: a date for TODAY(), the format of a date, currency or percent cell it refers to.
autoLinkstrueTurn typed web and mail addresses into links.
customListsnullYour own fill and sort lists, as arrays of strings. They save with the workbook.
autoFilterExtendstrueA row typed right below an AutoFilter joins it.
invalidFormulasfalseKeep a formula that doesn't parse, as text with a flag.
autoFitBasis"cell"What auto-fit measures: cell, or cellWithHeader to also leave room for the header text.
allowCellOverflowtrueText spills into empty neighbors, the way its alignment points.
colResizeMode"normal"Column resize: normal, or split to move only the boundary with the next column.
rowResizeMode"normal"Row resize: normal or split.
referenceStyle"A1"A1 or R1C1, in headers, the name box, the formula bar and typed formulas. Files store formulas in A1 form either way.
dynamicArraystrueFormulas may spill. False enters them as in older Excel, with implicit intersection.
iterativefalseCalculate circular references iteratively.
iterativeMaxIterations100Most iterations.
iterativeMaxChange0.001Smallest change that continues iterating.
calcOnDemandfalseCalculate only the cells on screen and those read through the API. Saving calculates the rest.
incrementalCalctrueCalculate in time slices, so input never blocks. False finishes each calculation before returning.
calculation"auto"auto or manual.
languagenullInterface language of the ribbon, menus, dialogs and messages: en or pl. Null keeps the user's choice from Preferences, else the browser's language. It is the page's, so workbooks on one page share it, and it is apart from the region, which sets how numbers and formulas read.
accessibilitytrueAnnounce the active cell to screen readers. False stops the announcements.
pivotReferences"getPivotData"What clicking a pivot value during formula entry inserts: getPivotData, as Excel does, or cell.
fileIconsnullIcons for file cells: extension to image URL, such as { pdf: "…" }.
focusHighlightnullHighlight the row and column of the active cell: { color, colColor, alpha }.

All commands

CommandLabelUndo stepDefault keys
edit.undoUndomod+z
edit.redoRedomod+shift+z, mod+y
edit.copyCopy
edit.cutCut
edit.pastePaste
edit.clearClear Contentsyesdelete, backspace
edit.clearAllClear Allyes
edit.selectAllSelect Allmod+a
edit.fillDownFill Downyesmod+d
edit.fillRightFill Rightyesmod+r
edit.autoSumAutoSumyes
edit.startEdit Cellf2
edit.toggleModeSwitch Enter and Edit
edit.commitEnter
edit.cancelCancel Edit
edit.inputEnter Valueyes
format.boldBoldyesmod+b
format.italicItalicyesmod+i
format.strikeStrikethroughyesmod+shift+x
format.underlineUnderlineyesmod+u
format.wrapWrap Textyes
format.styleFormat Cellsyes
format.fontNameFontyes
format.fontSizeFont Sizeyes
format.colorFont Coloryes
format.fillFill Coloryes
format.numFmtNumber Formatyes
format.hAlignAlignyes
format.vAlignVertical Alignyes
format.mergeMerge Cellsyes
format.unmergeUnmerge Cellsyes
format.cellStyleCell Styleyes
format.bordersBordersyes
rows.insertInsert Rowsyes
rows.deleteDelete Rowsyes
rows.hideHide Rowsyes
rows.unhideUnhide Rowsyes
rows.sizeRow Heightyes
cols.insertInsert Columnsyes
cols.deleteDelete Columnsyes
cols.hideHide Columnsyes
cols.unhideUnhide Columnsyes
cols.sizeColumn Widthyes
sheet.addInsert Sheetyes
sheet.removeDelete Sheet
sheet.renameRename Sheet
sheet.activateGo to Sheet
sheet.nextNext Sheetalt+arrowright
sheet.previousPrevious Sheetalt+arrowleft
sheet.freezeFreeze Panes
sheet.gridlinesGridlines
data.sortSortyes
data.filterFilteryes
data.clearFilterClear Filteryes
data.toggleFilterToggle Filteryesmod+shift+f
data.tableInsert Tableyes
nav.upMove Uparrowup
nav.downMove Downarrowdown
nav.leftMove Leftarrowleft
nav.rightMove Rightarrowright
nav.nextRowNext Rowenter
nav.nextColNext Columntab
nav.pageUpPage Uppageup
nav.pageDownPage Downpagedown
nav.rowStartStart of Rowhome
nav.sheetStartStart of Sheetmod+home
nav.sheetEndEnd of Sheetmod+end
nav.goToGo To
view.zoomZoom
view.zoomInZoom In
view.zoomOutZoom Out
file.printPrintmod+p
file.saveSavemod+s
file.saveAsSave As
file.openOpenmod+o
theme.applyTheme