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
| Call | Result | Keeps |
|---|
wb.toJSON() | plain data | The 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 handle | Everything, including what Excel can't hold. |
wb.saveXlsx(sink) | an xlsx file | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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. |
#Print defaults
| Member | What 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
| Member | What 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. |
| Member | What 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
| Member | What 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
| Member | What 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
| Member | What 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
| Event | Cancel | Needs a page | Fields | When |
|---|
before-change | yes | | label, sheet | An undoable edit is about to run. |
cells-changed | | | sheet, label, reason, count, bounds, cells() | Cells changed through any path: typing, paste, fill, API, undo or redo. cells() lists them lazily. |
step-done | | | sheet, label, reason | Any undoable step finished or was undone or redone, including ones that touch no cell, such as a format or a theme. |
bulk-written | | | sheet, bounds, count | A typed-array bulk write finished. It reports bounds instead of cells. |
before-structure | yes | | sheet, label | Rows or columns are about to be inserted or deleted. |
structure-changed | | | sheet, label, reason | Rows or columns were inserted or deleted. |
before-sort | yes | | sheet | A sort is about to run. |
range-sorting | | | sheet, range, info | A sort is working out its order; set info.compareFunction to compare two cell values your own way. |
sorted | | | sheet, reason | A sort finished. |
before-filter | yes | | sheet | A filter is about to change, from the API or a filter menu. |
filtered | | | sheet, reason | A filter was applied or cleared. |
invalid-operation | | | action, reason | An action was refused, for example by protection or a listener. |
#Selection
| Event | Cancel | Needs a page | Fields | When |
|---|
before-selection | yes | yes | sheet, from, to | The selection is about to change. |
selection-changed | | yes | sheet, from, to | The selection changed. |
cell-enter | | yes | sheet, row, col | The active cell moved onto a cell. |
cell-leave | | yes | sheet, row, col | The active cell left a cell. |
#Pointer
| Event | Cancel | Needs a page | Fields | When |
|---|
cell-click | | yes | sheet, hit, originalEvent | A click landed on a cell or header. The hit test is included. |
cell-double-click | yes | yes | sheet, hit, originalEvent | A double click landed on the grid. Cancelling stops the edit it would start. |
tab-click | | yes | sheet, index | A sheet tab was clicked. |
tab-double-click | | yes | sheet, index | A sheet tab was double clicked. |
#Editing
| Event | Cancel | Needs a page | Fields | When |
|---|
before-edit | yes | yes | sheet, row, col, initial, origin | A cell editor is about to open. |
edit-started | | yes | sheet, row, col, text, origin | The cell editor opened. |
edit-input | | yes | sheet, row, col, text | The text in the editor changed. |
before-commit | yes | yes | sheet, row, col, text | The editor is about to store its text. Set text to replace it; cancelling keeps the editor open. |
edit-ended | | yes | sheet, row, col, committed | The editor closed. |
editor-status | | yes | from, to | Editor status moved between ready, enter and edit. |
validation-failed | | yes | sheet, row, col, text, rule | Text entered in the editor breaks the cell's data validation rule. |
| Event | Cancel | Needs a page | Fields | When |
|---|
before-comment-change | yes | | sheet | A threaded comment is about to change. |
comment-changed | | | sheet | A threaded comment changed. |
before-mention | yes | | query | The list of people to mention is about to open. Cancel it and @ stays plain text. |
mentioned | | | person | A person was mentioned. |
#Clipboard
| Event | Cancel | Needs a page | Fields | When |
|---|
before-copy | yes | yes | sheet, ranges, cut | Copy or cut is about to run. |
after-copy | | yes | sheet, ranges, cut | Copy or cut finished. |
before-paste | yes | yes | sheet, ranges, text | Paste is about to run. text is the plain text on the clipboard. |
after-paste | | yes | sheet, ranges, text | Paste finished. |
#Sheets
| Event | Cancel | Needs a page | Fields | When |
|---|
before-active-sheet | yes | | from, to | The active sheet is about to change. |
active-sheet-changed | | | from, to | The active sheet changed. |
sheet-added | | | sheet | A sheet was added or duplicated. |
before-sheet-remove | yes | | sheet | A sheet is about to be deleted. |
sheet-removed | | | name | A sheet was deleted. |
before-sheet-rename | yes | | sheet, from, to | A sheet is about to be renamed. |
sheet-renamed | | | sheet, from, to | A sheet was renamed. |
before-sheet-move | yes | | sheet, from, to | A sheet is about to move. |
sheet-moved | | | sheet, from, to | A sheet moved. |
#Rows and columns
| Event | Cancel | Needs a page | Fields | When |
|---|
axis-resized | | | sheet, axis, indexes | Row or column sizes or hidden state changed. |
#drag
| Event | Cancel | Needs a page | Fields | When |
|---|
before-fill | yes | yes | sheet, from, to, mode | A fill drag is about to write its cells. |
filled | | yes | sheet, from, to, mode | A fill drag finished. |
before-drag-merge | yes | yes | sheet, range | A drag on the merge grip is about to merge cells. |
drag-merged | | yes | sheet, range | A drag on the merge grip merged cells. |
before-move | yes | yes | sheet, drag | Dragging the selection border is about to move or copy cells. |
cells-moved | | yes | sheet, drag | A drag moved or copied cells. |
#Calculation
| Event | Cancel | Needs a page | Fields | When |
|---|
calc-progress | | | remaining, total | A calculation slice finished on a large workbook. |
calc-end | | | | Calculation finished and all values are current. |
#View
| Event | Cancel | Needs a page | Fields | When |
|---|
before-zoom | yes | yes | from, zoom | The zoom is about to change. Set zoom to clamp it, or cancel. |
view-changed | | yes | zoom | The zoom changed. |
scrolled | | yes | x, y, topRow, leftCol | The grid scrolled. |
#Objects
| Event | Cancel | Needs a page | Fields | When |
|---|
object-selected | | yes | object | The selected chart, shape or picture changed. |
| Event | Cancel | Needs a page | Fields | When |
|---|
menu-opening | yes | yes | area, items, x, y, hit | A context menu is about to open. items can be edited in place. |
#Workbook
| Event | Cancel | Needs a page | Fields | When |
|---|
command-executed | | | name, args, result | A named command ran. |
before-print | yes | | sheets | A print or PDF job started through the API is about to run. |
theme-changed | | | theme | The workbook theme changed. |
user-changed | | | user | The current user changed. |
presence-changed | | | userId, presence | Someone started or stopped editing a range. |
workbook-loaded | | | source | A 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.
| Option | Default | What it does |
|---|
sheets | 1 | Number of sheets a new workbook starts with. |
defaultFont | null | Default font, such as { name: "Arial", size: 11 }. |
dragMerge | false | Merge cells by dragging the grip on the selection. |
dragHeaders | "none" | Move rows or columns by dragging their selected headers: none, row, col, both. |
dragDrop | true | Move cells by dragging the selection border. |
dragFill | true | Fill by dragging the corner handle. |
fillDefault | "auto" | What a fill drag does by default: auto, copy, series, formats, values. |
fillSmartTag | true | Show the options button after a fill drag. |
userZoom | true | Zoom with the pinch gesture and the status bar slider. |
userResize | true | Resize rows and columns by dragging their header edges. |
undo | true | Keep an undo history. False empties it and stops it growing. |
contextMenu | true | Show the right-click menu. |
deselect | true | Cmd or Ctrl and a click on a selected cell takes it out of the selection. |
touchLayout | false | Larger touch targets. |
hideSelection | false | Hide the selection while the workbook has no focus. |
zeroSizeMark | "none" | Mark rows and columns of size zero in the headers: none or lines. |
scrollbarV | true | Show the vertical scroll bar: true, false or auto. |
scrollbarH | true | Show the horizontal scroll bar: true, false or auto. |
scrollToMax | false | Size the scroll bars on the whole sheet instead of the used range. |
scrollAlignMax | false | Stop 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. |
scrollSkipsHidden | true | Hidden rows and columns take no room on the scroll bars. False gives them their room, so the thumb shows their position. |
pixelScroll | true | Scroll by pixel. False scrolls by whole rows and columns. |
scrollStep | 1 | Multiplies the distance of one wheel notch. |
tabStrip | true | Show the sheet tabs. |
tabStripShare | 0.6 | Share of the width the tab strip takes beside the horizontal scroll bar, from 0 to 1. |
renameTabs | true | Rename a sheet by double clicking its tab. |
reorderSheets | true | Move sheets by dragging their tabs. |
newSheetButton | true | Show the new-sheet button. |
sheetNavButtons | true | Show the previous and next sheet buttons. |
allSheetsList | "auto" | Show the button that lists all sheets: auto, true or false. |
tabStyles | null | Default look of sheet tabs: { color, background, activeColor, activeBackground, font }. |
copyIndicator | true | Show the moving border around copied cells. |
copyIndicatorColor | null | Color of that border. |
pasteExcelStyles | true | Keep the look of a table pasted from Excel or a web page. False pastes its text. |
pasteExtends | true | Paste 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. |
pasteSkipsHidden | false | Skip hidden rows and columns when pasting. |
background | null | Background color of the cell area. |
backgroundImage | null | Picture 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. |
emptyAreaColor | null | Color 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. |
dragFillTip | true | Show the fill value while dragging. |
dragDropTip | true | Show the target while dragging cells. |
flagInvalidData | false | Circle cells that break their validation rule. Costs only while on, and only for visible cells. |
editFormulas | true | Let the user enter and edit formulas in cells. False keeps formulas as they are and takes typed = as text. |
formulaBox | true | Show function lists and argument hints while typing a formula. |
formulaHint | true | A 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. |
autoLinks | true | Turn typed web and mail addresses into links. |
customLists | null | Your own fill and sort lists, as arrays of strings. They save with the workbook. |
autoFilterExtends | true | A row typed right below an AutoFilter joins it. |
invalidFormulas | false | Keep 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. |
allowCellOverflow | true | Text 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. |
dynamicArrays | true | Formulas may spill. False enters them as in older Excel, with implicit intersection. |
iterative | false | Calculate circular references iteratively. |
iterativeMaxIterations | 100 | Most iterations. |
iterativeMaxChange | 0.001 | Smallest change that continues iterating. |
calcOnDemand | false | Calculate only the cells on screen and those read through the API. Saving calculates the rest. |
incrementalCalc | true | Calculate in time slices, so input never blocks. False finishes each calculation before returning. |
calculation | "auto" | auto or manual. |
language | null | Interface 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. |
accessibility | true | Announce 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. |
fileIcons | null | Icons for file cells: extension to image URL, such as { pdf: "…" }. |
focusHighlight | null | Highlight the row and column of the active cell: { color, colColor, alpha }. |
#All commands
| Command | Label | Undo step | Default keys |
|---|
edit.undo | Undo | | mod+z |
edit.redo | Redo | | mod+shift+z, mod+y |
edit.copy | Copy | | |
edit.cut | Cut | | |
edit.paste | Paste | | |
edit.clear | Clear Contents | yes | delete, backspace |
edit.clearAll | Clear All | yes | |
edit.selectAll | Select All | | mod+a |
edit.fillDown | Fill Down | yes | mod+d |
edit.fillRight | Fill Right | yes | mod+r |
edit.autoSum | AutoSum | yes | |
edit.start | Edit Cell | | f2 |
edit.toggleMode | Switch Enter and Edit | | |
edit.commit | Enter | | |
edit.cancel | Cancel Edit | | |
edit.input | Enter Value | yes | |
format.bold | Bold | yes | mod+b |
format.italic | Italic | yes | mod+i |
format.strike | Strikethrough | yes | mod+shift+x |
format.underline | Underline | yes | mod+u |
format.wrap | Wrap Text | yes | |
format.style | Format Cells | yes | |
format.fontName | Font | yes | |
format.fontSize | Font Size | yes | |
format.color | Font Color | yes | |
format.fill | Fill Color | yes | |
format.numFmt | Number Format | yes | |
format.hAlign | Align | yes | |
format.vAlign | Vertical Align | yes | |
format.merge | Merge Cells | yes | |
format.unmerge | Unmerge Cells | yes | |
format.cellStyle | Cell Style | yes | |
format.borders | Borders | yes | |
rows.insert | Insert Rows | yes | |
rows.delete | Delete Rows | yes | |
rows.hide | Hide Rows | yes | |
rows.unhide | Unhide Rows | yes | |
rows.size | Row Height | yes | |
cols.insert | Insert Columns | yes | |
cols.delete | Delete Columns | yes | |
cols.hide | Hide Columns | yes | |
cols.unhide | Unhide Columns | yes | |
cols.size | Column Width | yes | |
sheet.add | Insert Sheet | yes | |
sheet.remove | Delete Sheet | | |
sheet.rename | Rename Sheet | | |
sheet.activate | Go to Sheet | | |
sheet.next | Next Sheet | | alt+arrowright |
sheet.previous | Previous Sheet | | alt+arrowleft |
sheet.freeze | Freeze Panes | | |
sheet.gridlines | Gridlines | | |
data.sort | Sort | yes | |
data.filter | Filter | yes | |
data.clearFilter | Clear Filter | yes | |
data.toggleFilter | Toggle Filter | yes | mod+shift+f |
data.table | Insert Table | yes | |
nav.up | Move Up | | arrowup |
nav.down | Move Down | | arrowdown |
nav.left | Move Left | | arrowleft |
nav.right | Move Right | | arrowright |
nav.nextRow | Next Row | | enter |
nav.nextCol | Next Column | | tab |
nav.pageUp | Page Up | | pageup |
nav.pageDown | Page Down | | pagedown |
nav.rowStart | Start of Row | | home |
nav.sheetStart | Start of Sheet | | mod+home |
nav.sheetEnd | End of Sheet | | mod+end |
nav.goTo | Go To | | |
view.zoom | Zoom | | |
view.zoomIn | Zoom In | | |
view.zoomOut | Zoom Out | | |
file.print | Print | | mod+p |
file.save | Save | | mod+s |
file.saveAs | Save As | | |
file.open | Open | | mod+o |
theme.apply | Theme | | |