1. Spreadsheet docs
  2. 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.

OptionWhat it does
partsWhich parts of the app show, and where. See Choose the parts.
chromeThe 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.
themeThe workbook theme (colours and fonts of the cells), a gallery name such as Lagoon or a theme built with wb.theme.build.
fileNameThe name in the title bar, and the default name when the user saves.
languageThe interface language, en or pl. Left out, the user's choice, else the browser's. See Languages.
sheetsHow many sheets a new workbook starts with. Only at mount.
datawb.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.

PartWhat it isCan be placed in your element
titleBarFile menu, quick buttons (open, save, undo, redo), the file name and the light or dark switchYes
ribbonThe ribbon tabs and their commandsYes
formulaBarThe name box and the formula barYes
nameBoxfalse hides only the name box inside the formula barNo
tabStripThe sheet tabs, with their scroll and new-sheet buttonsYes
statusBarStatus messages, selection statistics, view buttons and zoomYes
sidePanelsfalse keeps task panes, such as the chart format pane and the PivotTable field list, from taking roomNo
// 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:

UseParts
A full spreadsheet editor in your appAll 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:

ToSet
Stop formulas being typed or edited (a typed = is text)editFormulas: false
Turn off dragging cells, filling and resizingdragDrop: false, dragFill: false, userResize: false
Hide the right-click menucontextMenu: false
Lock sheet managementnewSheetButton: false, renameTabs: false, reorderSheets: false
Hide sheet tabstabStrip: false
Keep no undo historyundo: false
Calculate only on requestcalculation: 'manual', then wb.calculate()
Show R1C1 referencesreferenceStyle: 'R1C1'
Highlight the row and column of the active cellfocusHighlight: { color: '#2563eb', alpha: 0.12 }
Larger touch targetstouchLayout: 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. sheets and data throw a TypeError, because they act only when the workbook is made; use wb.addSheet() and wb.fromJSON().
  • theme given here is applied as wb.theme.apply applies it, so it is an undo step.
  • In the components, a refused key is reported once (React onError, the Vue error event, the Angular sheetError output) 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-edit keeps the cell editor from opening, so nothing can be typed.
  • before-change fires before every undoable edit, from the user or from code, with a label naming it, such as entry (typed text, and formulas from code), set-values (range.values from code), clear, format, sort, filter, structure (rows and columns), table, name, validation, format-rule, note, link, theme and others. Cancelling it refuses the edit and fires invalid-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 cancelling grid.insertSheet in before-command). Cancel before-sheet-remove, before-sheet-rename and before-sheet-move as 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.

OptionDefaultEffect
onlineFeaturestruefalse 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.
scriptstruefalse 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.