- Spreadsheet docs
- Developers
Embedding and options
Mount a workbook in your page, choose which parts of the app show, make it read-only, turn off online features and scripts, and change options while it runs.
mountWorkbook(element, options) puts a workbook into an element of your page and resolves to the workbook once it is ready. The full app is one composition of parts (title bar, ribbon, formula bar, grid, sheet tabs, status bar and task panes), and the options decide which of them show and how the grid behaves. Options can change later without mounting again.
The React, Vue and Angular components call mountWorkbook for you: their options prop or input takes exactly the same object.
Mount a workbook
JavaScript
import { mountWorkbook } from '@8sheets/core';
const host = document.querySelector('#sheet'); // needs a height, for example 600px
const wb = await mountWorkbook(host, {
fileName: 'Budget 2027',
chrome: 'light',
sheets: 3,
parts: { titleBar: false, sidePanels: false },
newSheetButton: false,
dragMerge: true,
});
// Later: change options in place.
document.querySelector('#compact').addEventListener('click', () => {
wb.setOptions({ parts: { ribbon: false, statusBar: false } });
});
// When the page or view goes away.
window.addEventListener('pagehide', () => wb.destroy());React
import { useState } from 'react';
import { Sheet } from '@8sheets/react';
export function Budget() {
const [compact, setCompact] = useState(false);
const options = {
fileName: 'Budget 2027',
chrome: 'light',
sheets: 3,
parts: { titleBar: false, sidePanels: false, ribbon: !compact, statusBar: !compact },
newSheetButton: false,
dragMerge: true,
};
return (
<>
<button onClick={() => setCompact((c) => !c)}>Compact view</button>
<div style={{ height: 600 }}>
<Sheet options={options} onError={(err) => console.warn(err)} />
</div>
</>
);
}Vue
<script setup>
import { reactive } from 'vue';
import { Sheet } from '@8sheets/vue';
const options = reactive({
fileName: 'Budget 2027',
chrome: 'light',
sheets: 3,
parts: { titleBar: false, sidePanels: false, ribbon: true, statusBar: true },
newSheetButton: false,
dragMerge: true,
});
function toggleCompact() {
options.parts.ribbon = !options.parts.ribbon;
options.parts.statusBar = options.parts.ribbon;
}
</script>
<template>
<button @click="toggleCompact">Compact view</button>
<Sheet :options="options" style="height: 600px" @error="(err) => console.warn(err)" />
</template>Angular
import { Component, signal } from '@angular/core';
import { SheetComponent, SheetOptions } from '@8sheets/angular';
@Component({
selector: 'app-budget',
imports: [SheetComponent],
template: `
<button (click)="toggleCompact()">Compact view</button>
<eight-sheet class="grid" [options]="options()" (sheetError)="warn($event)" />
`,
styles: `.grid { height: 600px; }`,
})
export class Budget {
options = signal<SheetOptions>({
fileName: 'Budget 2027',
chrome: 'light',
sheets: 3,
parts: { titleBar: false, sidePanels: false, ribbon: true, statusBar: true },
newSheetButton: false,
dragMerge: true,
});
toggleCompact() {
this.options.update((o) => {
const on = !(o.parts?.ribbon ?? true);
return { ...o, parts: { ...o.parts, ribbon: on, statusBar: on } };
});
}
warn(err: unknown) {
console.warn(err);
}
}The components compare options by value and send only the keys that changed to wb.setOptions, so the workbook isn't mounted again. sheets and data act only at mount.
Note The element needs a height. The workbook fills it completely, so give the element (or the component) a fixed height, or place it in a flex or grid layout that gives it one.
Mount options
These are the options that shape the workbook as it is made. Any option from the list of all options can be given alongside them.
| Option | What it does |
|---|---|
parts | Which parts of the app show, and where. See Choose the parts. |
chrome | The colours of the app around the cells: light, dark, auto (follows the system), a named skin such as slate, or your own skin. See Themes and skins. |
theme | The workbook theme (colours and fonts of the cells), a gallery name such as Lagoon or a theme built with wb.theme.build. |
fileName | The name in the title bar, and the default name when the user saves. |
language | The interface language, en or pl. Left out, the user's choice, else the browser's. See Languages. |
sheets | How many sheets a new workbook starts with. Only at mount. |
data | wb.toJSON() output to load. Only at mount; later use wb.fromJSON(). |
Choose the parts
Each entry in parts is true (shown, the default), false (left out), or an element of your page to place that part in.
| Part | What it is | Can be placed in your element |
|---|---|---|
titleBar | File menu, quick buttons (open, save, undo, redo), the file name and the light or dark switch | Yes |
ribbon | The ribbon tabs and their commands | Yes |
formulaBar | The name box and the formula bar | Yes |
nameBox | false hides only the name box inside the formula bar | No |
tabStrip | The sheet tabs, with their scroll and new-sheet buttons | Yes |
statusBar | Status messages, selection statistics, view buttons and zoom | Yes |
sidePanels | false keeps task panes, such as the chart format pane and the PivotTable field list, from taking room | No |
// A grid with tabs, and the status bar in your own footer.
await mountWorkbook(document.querySelector('#grid'), {
parts: {
titleBar: false,
ribbon: false,
formulaBar: false,
sidePanels: false,
statusBar: document.querySelector('#footer'),
},
});
A ribbon left out at mount doesn't load at all, and context menus use a smaller menu instead. It also can't be brought back later: setOptions({ parts: { ribbon: true } }) throws a TypeError. A ribbon mounted hidden or shown can be toggled, and so can the other parts. A part placed in an element of yours stays there until the workbook is mounted again. To keep the ribbon but take away some of its controls, groups or tabs, hide them by id; see Control everything from code. The code for charts, slicers, PivotTables and data sheets loads whichever parts you choose, because opening and saving a file needs it.
Typical compositions:
| Use | Parts |
|---|---|
| A full spreadsheet editor in your app | All parts (the default), perhaps titleBar: false |
| Data entry in a form | { titleBar: false, ribbon: false, sidePanels: false }, with tabStrip: false for one sheet |
| A report viewer | { titleBar: false, ribbon: false, formulaBar: false, sidePanels: false }, plus the read-only setup below |
Options that control behaviour
Every option has a default that matches the desktop spreadsheet experience. The ones most often changed:
| To | Set |
|---|---|
Stop formulas being typed or edited (a typed = is text) | editFormulas: false |
| Turn off dragging cells, filling and resizing | dragDrop: false, dragFill: false, userResize: false |
| Hide the right-click menu | contextMenu: false |
| Lock sheet management | newSheetButton: false, renameTabs: false, reorderSheets: false |
| Hide sheet tabs | tabStrip: false |
| Keep no undo history | undo: false |
| Calculate only on request | calculation: 'manual', then wb.calculate() |
| Show R1C1 references | referenceStyle: 'R1C1' |
| Highlight the row and column of the active cell | focusHighlight: { color: '#2563eb', alpha: 0.12 } |
| Larger touch targets | touchLayout: true |
The list of all options has every option, its default and its values.
Change options later
wb.setOptions(patch) changes options of a mounted workbook at once. Only the keys you pass change.
wb.setOptions({ chrome: 'dark', parts: { statusBar: false } });
wb.setOptions({ parts: undefined }); // a key given as undefined or null goes back to its default
console.log(wb.options); // the options as they apply now
- The whole patch is checked first, so a patch that throws changes nothing.
- An unknown option or a bad value throws a
RangeError.sheetsanddatathrow aTypeError, because they act only when the workbook is made; usewb.addSheet()andwb.fromJSON(). themegiven here is applied aswb.theme.applyapplies it, so it is an undo step.- In the components, a refused key is reported once (React
onError, the Vueerrorevent, the AngularsheetErroroutput) and the other changed keys still apply.
Read-only workbooks
There is no single read-only switch. A read-only view combines options that remove the editing tools with cancellable events that refuse edits:
JavaScript
import { mountWorkbook } from '@8sheets/core';
const wb = await mountWorkbook(document.querySelector('#report'), {
parts: { titleBar: false, ribbon: false, formulaBar: false, sidePanels: false },
contextMenu: false,
dragDrop: false,
dragFill: false,
newSheetButton: false,
renameTabs: false,
reorderSheets: false,
});
// Fill the workbook first: while the before-change listener is on, writes from code are refused too.
const blob = await (await fetch('/reports/q3.xlsx')).blob();
await wb.openFile(blob, { name: 'q3.xlsx' });
wb.commands.disableKey('shift+f11'); // the Insert Sheet shortcut
wb.events.on('before-edit', (e) => e.cancel()); // no cell editor opens
const stopRefusing = wb.events.on('before-change', (e) => {
if (e.label !== 'sort' && e.label !== 'filter') e.cancel(); // allow sorting and filtering
});React
import { Sheet } from '@8sheets/react';
const options = {
parts: { titleBar: false, ribbon: false, formulaBar: false, sidePanels: false },
contextMenu: false, dragDrop: false, dragFill: false,
newSheetButton: false, renameTabs: false, reorderSheets: false,
};
export function Report({ url }) {
async function load(wb) {
const blob = await (await fetch(url)).blob();
await wb.openFile(blob, { name: 'report.xlsx' });
wb.commands.disableKey('shift+f11');
wb.events.on('before-change', (e) => { if (e.label !== 'sort' && e.label !== 'filter') e.cancel(); });
}
return (
<div style={{ height: 600 }}>
<Sheet options={options} onReady={load} onBeforeEdit={(e) => e.cancel()} />
</div>
);
}Vue
<script setup>
import { Sheet } from '@8sheets/vue';
const props = defineProps({ url: String });
const options = {
parts: { titleBar: false, ribbon: false, formulaBar: false, sidePanels: false },
contextMenu: false, dragDrop: false, dragFill: false,
newSheetButton: false, renameTabs: false, reorderSheets: false,
};
async function load(wb) {
const blob = await (await fetch(props.url)).blob();
await wb.openFile(blob, { name: 'report.xlsx' });
wb.commands.disableKey('shift+f11');
wb.events.on('before-change', (e) => { if (e.label !== 'sort' && e.label !== 'filter') e.cancel(); });
}
</script>
<template>
<Sheet :options="options" style="height: 600px" @ready="load" @before-edit="(e) => e.cancel()" />
</template>Angular
import { Component, Input } from '@angular/core';
import { SheetComponent, SheetEventPayload, SheetOptions, SheetsWorkbook } from '@8sheets/angular';
@Component({
selector: 'app-report',
imports: [SheetComponent],
template: `<eight-sheet class="grid" [options]="options" (ready)="load($event)" (beforeEdit)="refuse($event)" />`,
styles: `.grid { height: 600px; }`,
})
export class Report {
@Input() url = '/reports/q3.xlsx';
options: SheetOptions = {
parts: { titleBar: false, ribbon: false, formulaBar: false, sidePanels: false },
contextMenu: false, dragDrop: false, dragFill: false,
newSheetButton: false, renameTabs: false, reorderSheets: false,
};
async load(wb: SheetsWorkbook) {
const blob = await (await fetch(this.url)).blob();
await wb.openFile(blob, { name: 'report.xlsx' });
wb.commands.disableKey('shift+f11');
wb.events.on('before-change', (e) => { if (e['label'] !== 'sort' && e['label'] !== 'filter') e.cancel(); });
}
refuse(e: SheetEventPayload) {
e.cancel();
}
}What this does:
before-editkeeps the cell editor from opening, so nothing can be typed.before-changefires before every undoable edit, from the user or from code, with alabelnaming it, such asentry(typed text, and formulas from code),set-values(range.valuesfrom code),clear,format,sort,filter,structure(rows and columns),table,name,validation,format-rule,note,link,themeand others. Cancelling it refuses the edit and firesinvalid-operation. The sample lets sorting and filtering through, so readers can still explore the data.- Adding a sheet doesn't pass through
before-change, so it is closed off by the options (newSheetButton, the ribbon and the context menu left out) and by turning off its shortcut, Shift+F11 (or cancellinggrid.insertSheetinbefore-command). Cancelbefore-sheet-remove,before-sheet-renameandbefore-sheet-moveas well if any path to them is left open. - This setup refuses typing, Delete, formatting shortcuts, Shift+F11 and writes from code. Check the other paths your users have, such as pasting from the clipboard or dragging charts and pictures, in your own app.
- Selecting, scrolling, copying, switching sheets and zooming still work.
wb.events.on returns a function that removes the listener. Call it (as stopRefusing() above) before you change cells from code, and add the listener again afterwards.
Sheet protection (sheet.protect()) is the other tool: it locks cells for the user as Excel does, travels with the saved file, and leaves cells with the unlocked style editable. It does not stop writes from your code, and a user with the ribbon can turn it off. See Working with data.
Online features, scripts and unavailable commands
Three options decide what the embedded app may do beyond your page. They are the usual choices for a host that shows the spreadsheet next to business data.
| Option | Default | Effect |
|---|---|---|
onlineFeatures | true | false leaves out every feature that reaches another site and makes those features refuse to run: Get Data From Web, data sheets bound to a web address, WEBSERVICE, pictures from IMAGE and SPARK_IMAGE, the AI features, and a collaboration server on another site. Cells that use them show #BLOCKED!, and no redirect is followed, so cell data never leaves for another site. Addresses on your page's own site keep working. It is the page's setting, so all workbooks on a page share it. |
scripts | true | false leaves out the Automate tab, View > Macros and Record Actions, and refuses to run scripts. Scripts run in your page with its rights, so a host that holds other data may not want them. |
unavailableCommands | 'hide' | Commands Excel has that 8sheets can't run are left out of the ribbon, and so is a group left with nothing usable. 'show' keeps them, disabled, with the reason in their tip. |
const wb = await mountWorkbook(host, { onlineFeatures: false, scripts: false });
Turning onlineFeatures off during a session with a collaboration server on another site ends that session. See Security and hosting for the rest of the checklist.
Several workbooks on one page
Several workbooks can share a page, each with its own options, events and Worker. Keyboard and clipboard input goes to the one last clicked or focused. The interface language and onlineFeatures are the page's and apply to all of them.
Clean up
wb.destroy() removes the workbook from the page and releases its listeners, Worker, timers and frames. It is safe to call twice. The components call it for you when they unmount, also when that happens while the workbook is still loading.