1. Spreadsheet docs
  2. Developers

React, Vue and Angular

The 8sheets components for React, Vue and Angular: their props, events, refs, server rendering and lifecycle.

There is a component for each of the three frameworks, on npm as @8sheets/react, @8sheets/vue and @8sheets/angular. Each one mounts a workbook in an element it owns, passes your options through, turns workbook events into the framework's own events, gives you the workbook for everything else, and destroys it when the component goes away. Install one together with @8sheets/core; Installation has the bundler settings.

All three follow the same contract:

ReactVueAngular
Component<Sheet><Sheet><eight-sheet> (SheetComponent)
Optionsoptions propoptions prop[options] input
Workbook readyonReady(wb)@ready(ready)
ErrorsonError(err)@error(sheetError)
A workbook eventonCellsChanged@cells-changed(cellsChanged)
The workbookref.current.workbooktemplate ref .workbook, or useSheet()component.workbook
Open and saveopenFile(file), saveXlsx(sink) on the refopenFile(file), saveXlsx(sink), whenReady() on the refopenFile(file), saveXlsx(sink?) on the component
Server renderingRenders an empty <div>; marked 'use client'Renders an empty <div>; use <ClientOnly> in NuxtMounts in afterNextRender, never on the server

The smallest working component

Each of these mounts a workbook, fills a cell, logs edits, and cleans up when it goes away. The JavaScript tab shows what the components do for you.

JavaScript

import { mountWorkbook } from '@8sheets/core';

// Called from your code, not awaited at the top level of the entry module (see Installation > Vite).
async function showWorkbook() {
  const wb = await mountWorkbook(document.querySelector('#sheet'), { chrome: 'light' });
  wb.activeSheet.range('A1').values = 'Hello';
  const off = wb.events.on('cells-changed', (e) => console.log(e.count, 'cells changed'));
  // when the view goes away:
  // off(); wb.destroy();
  return wb;
}
showWorkbook();

React

import { Sheet } from '@8sheets/react';

export function Hello() {
  return (
    <div style={{ height: 400 }}>
      <Sheet
        options={{ chrome: 'light' }}
        onReady={(wb) => { wb.activeSheet.range('A1').values = 'Hello'; }}
        onCellsChanged={(e) => console.log(e.count, 'cells changed')}
      />
    </div>
  );
}

Vue

<script setup>
import { Sheet } from '@8sheets/vue';

const hello = (wb) => { wb.activeSheet.range('A1').values = 'Hello'; };
</script>

<template>
  <Sheet :options="{ chrome: 'light' }" style="height: 400px" @ready="hello" @cells-changed="(e) => console.log(e.count, 'cells changed')" />
</template>

Angular

import { Component } from '@angular/core';
import { SheetComponent, SheetEventPayload, SheetsWorkbook } from '@8sheets/angular';

@Component({
  selector: 'app-hello',
  imports: [SheetComponent],
  template: `<eight-sheet class="grid" [options]="{ chrome: 'light' }" (ready)="hello($event)" (cellsChanged)="log($event)" />`,
  styles: `.grid { height: 400px; }`,
})
export class Hello {
  hello(wb: SheetsWorkbook) {
    wb.activeSheet.range('A1').values = 'Hello';
  }

  log(e: SheetEventPayload) {
    console.log(e['count'], 'cells changed');
  }
}

Note The workbook needs a height. Each component fills its container, so give the container, or the component itself, a height.

Events in each framework

Every workbook event in the API reference is available. The name changes only in spelling:

Workbook eventReact propVue listenerAngular output
cells-changedonCellsChanged@cells-changed(cellsChanged)
selection-changedonSelectionChanged@selection-changed(selectionChanged)
before-sheet-removeonBeforeSheetRemove@before-sheet-remove(beforeSheetRemove)
calc-endonCalcEnd@calc-end(calcEnd)
before-commandonBeforeCommand@before-command(beforeCommand)
after-commandonAfterCommand@after-command(afterCommand)

The handler gets the workbook's event object: type, workbook, cancel() and the fields of that event. Call e.cancel() in a before-… handler to stop the action; handlers run synchronously, so this works in all three. Each component subscribes only to the events you listen to, and a workbook installs the hooks for a group of events only while that group has a listener, so events you don't use cost nothing. See Events.

React

<Sheet> works with React 18 and 19, StrictMode included. It is written without JSX, so it needs no build step of its own, and its types cover every prop and the ref.

import { useRef, useState } from 'react';
import { Sheet } from '@8sheets/react';

const options = { chrome: 'light', parts: { titleBar: false } };

export function Budget() {
  const sheet = useRef(null);
  const [selected, setSelected] = useState('A1');

  async function download() {
    const chunks = [];
    await sheet.current.saveXlsx({ write: async (bytes) => { chunks.push(bytes.slice()); } });
    const url = URL.createObjectURL(new Blob(chunks));
    Object.assign(document.createElement('a'), { href: url, download: 'budget.xlsx' }).click();
    URL.revokeObjectURL(url);
  }

  return (
    <>
      <p>Selected: {selected} <button onClick={download}>Download</button></p>
      <div style={{ height: 480 }}>
        <Sheet
          ref={sheet}
          options={options}
          onReady={(wb) => { wb.activeSheet.range('A1').values = [['Item', 'Cost'], ['Rent', 1450]]; }}
          onSelectionChanged={(e) => setSelected(e.workbook.selectedRanges.map((r) => r.address).join(', '))}
          onBeforeSheetRemove={(e) => { if (!confirm(`Delete ${e.sheet.name}?`)) e.cancel(); }}
          onError={(err) => console.error(err)}
        />
      </div>
    </>
  );
}

Props

PropWhat it does
optionsGiven to mountWorkbook. After mount it is compared by value, and only the changed keys go to wb.setOptions, without a remount. A removed key goes back to its default. data and sheets act only at mount, like defaultValue.
on…One prop per workbook event, named on plus the event name in camel case.
onReady(wb)Called once with the workbook, after it mounted and the event props are subscribed.
onError(err)A mount that failed, or an option setOptions refused. Without it the error goes to console.error.
className, stylePassed to the <div>, which is 100% wide and high by default.

The ref (type SheetRef) has workbook (null before onReady and after unmount), openFile(file, { name }) for a File or a Blob, and saveXlsx(sink). Everything else is on workbook.

The component always calls the handler from the latest render, so an inline arrow function never causes a re-subscription. Keep the options object stable (outside the component, in state or in useMemo) or build it in render, as you like: it is compared by value either way. Events fired while the workbook mounts, such as workbook-loaded from options.data, come before the subscription; read that state in onReady.

EVENT_PROPS (prop name to event name) and eventProp(name) are exported for code that builds handlers dynamically.

Next.js. The package is marked 'use client'. Render <Sheet> from a client component, or load it with dynamic(() => import('@8sheets/react').then((m) => m.Sheet), { ssr: false }); dynamic() doesn't forward refs, so use onReady there. Both Turbopack and webpack build it with no configuration.

Vue

Sheet works with Vue 3.4 and later. It is a plain ES module with a render function, so it needs no Vue compiler, and its types cover the props, events and exposed members.

<script setup>
import { reactive, ref } from 'vue';
import { Sheet, useSheet } from '@8sheets/vue';

const options = reactive({ chrome: 'light', parts: { titleBar: false } });
const { sheet, workbook } = useSheet();   // <Sheet ref="sheet" />; workbook is a computed ref
const selected = ref('A1');

function onReady(wb) {
  wb.activeSheet.range('A1').values = [['Item', 'Cost'], ['Rent', 1450]];
}
function onSelection(e) {
  selected.value = e.workbook.selectedRanges.map((r) => r.address).join(', ');
}
function confirmRemove(e) {
  if (!confirm(`Delete ${e.sheet.name}?`)) e.cancel();
}
async function addSheet() {
  const wb = await sheet.value.whenReady();
  wb.addSheet('Notes');
}
</script>

<template>
  <p>Selected: {{ selected }} <button @click="addSheet">Add a sheet</button></p>
  <Sheet
    ref="sheet"
    :options="options"
    style="height: 480px"
    @ready="onReady"
    @selection-changed="onSelection"
    @before-sheet-remove="confirmRemove"
    @error="(err) => console.error(err)"
  />
</template>

Props and events. options is the only prop. It is watched deeply (but not inside data), and a change sends only the changed keys to wb.setOptions. Events are ready(workbook), error(err) and one per workbook event under its own kebab-case name; SHEET_EVENTS lists them. A listener added or removed after mount, such as @cells-changed="logging ? onCells : undefined", subscribes or unsubscribes at once.

The template ref exposes workbook, whenReady() (a promise of the workbook that rejects if the component unmounts first or mounting fails), openFile(file) and saveXlsx(sink). useSheet() returns that ref and a computed workbook.

Don't put the workbook in reactive() or a deep ref(): Vue would wrap it in proxies. Keep it in a shallowRef, as the component does.

Nuxt. Wrap the component in <ClientOnly> and set vite: { worker: { format: 'es' } } in nuxt.config.ts.

Angular

<eight-sheet> is a standalone component for Angular 17 and later, with zone.js or zoneless, and with server rendering. Its outputs are typed.

import { Component, ViewChild, signal } from '@angular/core';
import { SheetComponent, SheetEventPayload, SheetOptions, SheetsWorkbook } from '@8sheets/angular';

@Component({
  selector: 'app-budget',
  imports: [SheetComponent],
  template: `
    <p>Selected: {{ selected() }} <button (click)="download()">Download</button></p>
    <eight-sheet
      class="grid"
      [options]="options()"
      (ready)="onReady($event)"
      (selectionChanged)="onSelection($event)"
      (beforeSheetRemove)="confirmRemove($event)"
      (sheetError)="onError($event)"
    />
  `,
  styles: `.grid { height: 480px; }`,
})
export class Budget {
  @ViewChild(SheetComponent) sheet?: SheetComponent;
  options = signal<SheetOptions>({ chrome: 'light', parts: { titleBar: false } });
  selected = signal('A1');

  onReady(wb: SheetsWorkbook) {
    wb.activeSheet.range('A1').values = [['Item', 'Cost'], ['Rent', 1450]];
  }

  onSelection(e: SheetEventPayload) {
    this.selected.set(e.workbook.selectedRanges.map((r: { address: string }) => r.address).join(', '));
  }

  confirmRemove(e: SheetEventPayload) {
    if (!confirm(`Delete ${e['sheet'].name}?`)) e.cancel();
  }

  async download() {
    const blob = (await this.sheet!.saveXlsx()) as Blob;   // without a sink it returns a Blob
    const url = URL.createObjectURL(blob);
    Object.assign(document.createElement('a'), { href: url, download: 'budget.xlsx' }).click();
    URL.revokeObjectURL(url);
  }

  onError(err: unknown) {
    console.error(err);
  }
}

Input. options takes everything mountWorkbook takes. Pass a new object to change options: the component compares it by value, key by key, and sends only the changed keys to wb.setOptions. options is an @Input(), so you can bind a signal with [options]="options()". A change that arrives while the workbook is still mounting is applied before ready fires.

Outputs. ready fires once with the SheetsWorkbook. sheetError fires when the mount fails or setOptions refuses an option; unbound, the error goes to Angular's ErrorHandler. Every workbook event has an output named in camel case. Read event fields with brackets, as in $event['count']. An output nobody binds doesn't listen to the workbook.

The component has workbook (null before ready and after destroy), openFile(file) and saveXlsx(sink?), which returns a Blob when given no sink. Both methods throw before ready.

Change detection. The component mounts the workbook, applies options and runs openFile and saveXlsx outside Angular's zone, so the grid's pointer, scroll, keyboard, timer and Worker callbacks never run change detection. A bound output re-enters the zone to emit, so your handler runs inside it and the view updates. In a zoneless app, signals you set in a handler update the view as usual.

Loading. 8sheets is served as static files next to your app and loaded at run time, only on pages that show a sheet: one entry in the assets of angular.json (see Installation). Provide EIGHT_SHEETS_URL to load it from another path. Import only types from @8sheets/core in Angular code.

Server rendering. The component mounts in afterNextRender, which runs only in the browser. On the server it renders an empty <eight-sheet> and never loads 8sheets. With hydration, the workbook mounts after the page hydrates.

Changing options

In all three, a new value for options changes the workbook in place: only the keys that changed go to wb.setOptions(), and the workbook is not mounted again. Colours, theme, language, file name, which parts are shown and every option in the API reference can change this way. A key you remove goes back to its default, and a part you remove from parts shows again. data and sheets act only when the workbook is mounted; use wb.fromJSON() and wb.addSheet() after that. When setOptions refuses a value, the error is reported once and the other changed keys still apply.

Several sheets, and cleaning up

Several components can share a page, and each one sends its events only to its own handlers. Keyboard and clipboard input goes to the one last clicked or focused. When a component goes away, its workbook is destroyed completely: no Worker, timer or page listener is left behind. A component removed while its workbook is still loading destroys it as soon as it arrives.

Other frameworks

Everything the components do is in the JavaScript API: mount in the framework's "mounted" hook, subscribe with wb.events.on, pass changes to wb.setOptions, and destroy in its "unmounted" hook.

import { mountWorkbook } from '@8sheets/core';

let wb = null;
let destroyed = false;

export async function attach(element, options) {
  const mounted = await mountWorkbook(element, options);
  if (destroyed) { mounted.destroy(); return; }   // the view went away while loading
  wb = mounted;
  const off = wb.events.on('cells-changed', (e) => console.log(e.count, 'cells changed'));
  return () => { off(); wb.destroy(); };
}

export function detach() {
  destroyed = true;
  wb?.destroy();
}

Examples in the source download

Each component folder in the source download has an example app with two sheets, option toggles, a save-and-open round trip, an event log and a browser test that checks mounting, events, option changes and that unmounting leaves nothing behind.