- Spreadsheet docs
- Developers
Large files and performance
How 8sheets stays fast with large workbooks, and how to load, write, calculate and listen to big data efficiently from code.
8sheets is built for workbooks far beyond what fits comfortably in a DOM table. A workbook of 1,000,000 rows by 20 columns is part of its regular performance tests. This page explains what makes that work and what your code should do to keep it so.
What the engine does for you
- Files stream in a Worker. Opening reads the ZIP package entry by entry and parses the XML as a stream in a background thread, sending cells to the page in batches with acknowledgements, so the page stays responsive and the first rows show while the rest is loading. Saving works the same way in reverse. A file is never held in memory in one piece.
- Compact storage. Cells live in chunked typed arrays, not one JavaScript object per cell, and shared strings stay encoded until a cell is drawn.
- Drawing costs only what is on screen. The grid is a canvas, and drawing a frame depends on the visible area, not on the size of the sheet.
- Calculation in time slices. Formulas are compiled once and recalculated through a dependency graph, so a change recalculates only what depends on it. Work longer than one slice of about 10 ms continues in the background, so typing never waits for a large recalculation.
- Events cost nothing until you listen. The hooks for an event group are installed only while it has a listener.
The large sample opens 100,000 orders in 10 columns, a million cells, and shows in its status bar how long that took.
Load large data from code
range.values takes plain arrays and is right for most data. For hundreds of thousands of cells, write typed arrays straight into storage, one array per column, and skip the undo copy for fresh data:
JavaScript
import { mountWorkbook } from '@8sheets/core';
const wb = await mountWorkbook(document.querySelector('#sheet'));
loadColumns(wb, await (await fetch('/api/prices.json')).json());
function loadColumns(wb, { skus, prices, stock }) {
const sheet = wb.activeSheet;
const n = skus.length;
sheet.range('A1').values = [['SKU', 'Price', 'Stock', 'Value']];
sheet.range('A2').setStrings([skus], { undoable: false });
sheet.range('B2').setNumbers([Float64Array.from(prices), Float64Array.from(stock)], { undoable: false });
sheet.range(`D2:D${n + 1}`).formulas = '=B2*C2';
sheet.range('B:B').style = { numFmt: '#,##0.00' }; // one record for the whole column
wb.history.clear();
}
wb.events.on('calc-progress', (e) => console.log(`${e.total - e.remaining} of ${e.total}`));
await wb.whenCalculated();React
import { Sheet } from '@8sheets/react';
function loadColumns(wb, { skus, prices, stock }) {
const sheet = wb.activeSheet;
sheet.range('A1').values = [['SKU', 'Price', 'Stock', 'Value']];
sheet.range('A2').setStrings([skus], { undoable: false });
sheet.range('B2').setNumbers([Float64Array.from(prices), Float64Array.from(stock)], { undoable: false });
sheet.range(`D2:D${skus.length + 1}`).formulas = '=B2*C2';
sheet.range('B:B').style = { numFmt: '#,##0.00' };
wb.history.clear();
}
export function Prices({ data }) {
return (
<div style={{ height: 640 }}>
<Sheet onReady={(wb) => loadColumns(wb, data)} onCalcEnd={() => console.log('values are current')} />
</div>
);
}Vue
<script setup>
import { Sheet } from '@8sheets/vue';
const props = defineProps({ data: Object });
function loadColumns(wb) {
const { skus, prices, stock } = props.data;
const sheet = wb.activeSheet;
sheet.range('A1').values = [['SKU', 'Price', 'Stock', 'Value']];
sheet.range('A2').setStrings([skus], { undoable: false });
sheet.range('B2').setNumbers([Float64Array.from(prices), Float64Array.from(stock)], { undoable: false });
sheet.range(`D2:D${skus.length + 1}`).formulas = '=B2*C2';
sheet.range('B:B').style = { numFmt: '#,##0.00' };
wb.history.clear();
}
</script>
<template>
<Sheet style="height: 640px" @ready="loadColumns" @calc-end="() => console.log('values are current')" />
</template>Angular
import { Component, Input } from '@angular/core';
import { SheetComponent, SheetsWorkbook } from '@8sheets/angular';
interface PriceData { skus: string[]; prices: number[]; stock: number[] }
@Component({
selector: 'app-prices',
imports: [SheetComponent],
template: `<eight-sheet class="grid" (ready)="loadColumns($event)" (calcEnd)="done()" />`,
styles: `.grid { height: 640px; }`,
})
export class Prices {
@Input() data!: PriceData;
loadColumns(wb: SheetsWorkbook) {
const { skus, prices, stock } = this.data;
const sheet = wb.activeSheet;
sheet.range('A1').values = [['SKU', 'Price', 'Stock', 'Value']];
sheet.range('A2').setStrings([skus], { undoable: false });
sheet.range('B2').setNumbers([Float64Array.from(prices), Float64Array.from(stock)], { undoable: false });
sheet.range(`D2:D${skus.length + 1}`).formulas = '=B2*C2';
sheet.range('B:B').style = { numFmt: '#,##0.00' };
wb.history.clear();
}
done() {
console.log('values are current');
}
}| Call | What it writes |
|---|---|
range.setNumbers(columns, options) | One Float64Array per column, copied into storage chunk by chunk. NaN writes an empty cell. |
range.setStrings(columns, options) | One array of strings per column, through the string table. null writes an empty cell. |
range.setStyleIds(columns, options) | One Uint16Array of style ids per column. Get an id with wb.styleId({ bold: true }). |
range.numbers(x) | Reads one column of the range as a Float64Array; cells that aren't numbers read as NaN. |
range.styleIds(x) | Reads one column's style ids, for reuse. |
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 table column; a values write under 4,096 cells does.
Write in few, large steps
- One write per block, not per cell.
range('A2').values = rowswith an array of rows is one step; a loop of single-cell writes is thousands of steps, each with its own undo record and events. - Group edits with
wb.history.transaction(label, fn), so they become one undo step and listeners hear about them once. - Style whole rows and columns (
range('B:B').style = …): it costs one record, not one per cell. - Fill formulas by writing one string to a range (
range('D2:D200000').formulas = '=B2*C2'); the references adjust as a fill does. - Clear the history after loading data the user shouldn't undo, or mount with
undo: falsefor a workbook that never needs it.
Calculation
| Option or call | Effect |
|---|---|
incrementalCalc: true (default) | Calculate in time slices, so input never blocks. false finishes each calculation before returning. |
calcOnDemand: true | Calculate only the cells on screen and the cells read through the API. Saving calculates the rest. |
calculation: 'manual' | Recalculate only on wb.calculate() or F9. |
await wb.whenCalculated() | Waits until every formula is current. saveXlsx and PDF export wait for it themselves. |
calc-progress, calc-end | Report progress (remaining, total) on a large workbook, and the end. |
Volatile functions such as NOW and RAND recalculate on every change; avoid them in large models when a fixed value will do.
Cross-origin isolation
When the page is cross-origin isolated, 8sheets can use SharedArrayBuffer. It runs without it otherwise. To turn it on, send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: credentialless; see Security and hosting.
Listeners
Listen to the events you need and keep handlers on frequent events light: scrolled, edit-input, cell-enter and selection-changed can fire many times a second. For cells-changed after a paste or fill, check e.count and e.bounds before walking e.cells().
Limits
How large a file can be opened depends on the device's memory and the browser's limits. A sheet holds at most 1,048,576 rows by 16,384 columns, as in Excel. Measure your own heaviest workbooks in the app before you decide.