- Data Grid docs
- Data
Local files and arrays
Open XLSX, CSV and TSV files in the browser, or pass records as arrays of objects, arrays of rows or typed-array columns.
Local data lives in the grid's Worker: the browser reads it once, and every search, sort and total runs there. Use it for records your page already has, and for files the user picks. Nothing is uploaded.
Open the large example: 1,000,000 records
Records you pass
data takes three shapes:
| Shape | Example | Notes |
|---|---|---|
| Array of objects | [{ Region: 'East', Units: 2 }] | Field names come from fields, or from the records. |
| Array of rows | [['Region', 'Units'], ['East', 2], ['West', 5]] | Without fields, the first row holds the field names. With fields, every row is a record, in the order of fields. |
| Columns | { Region: ['East', 'West'], Units: new Float64Array([2, 5]) } | Arrays or typed arrays, one per field. The fastest form for large data. |
With fields, give each field a type (string, number, date, boolean or any), and optionally a caption, an Excel number format such as #,##0.00 or yyyy-mm-dd, and a formula for a calculated field. Dates are Excel serial numbers in a date field.
JavaScript
import { mountTable } from '@8sheets/data-grid';
// A million records as columns: the buffers move to the Worker without a copy.
const n = 1_000_000;
const units = new Float64Array(n);
const price = new Float64Array(n);
for (let i = 0; i < n; i++) {
units[i] = 1 + (i % 50);
price[i] = 2 + (i % 17) * 1.25;
}
const grid = await mountTable(document.querySelector('#orders'), {
title: 'Orders',
fields: [
{ name: 'Units', type: 'number' },
{ name: 'Price', type: 'number', format: '#,##0.00' },
],
data: { Units: units, Price: price },
transferColumns: true, // the page gives up the buffers; don't use them afterwards
});React
import { useMemo } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
const fields = [
{ name: 'Region', type: 'string' },
{ name: 'Units', type: 'number' },
{ name: 'Shipped', type: 'date', format: 'yyyy-mm-dd' },
];
export function Orders({ rows }) {
// rows: [['East', 2, 46336], ['West', 5, 46337], …] (dates as Excel serial numbers)
const options = useMemo(() => ({ title: 'Orders', fields, data: rows }), [rows]);
return <div style={{ height: 480 }}><DataGrid options={options} /></div>;
}Vue
<script setup>
import { computed, shallowRef } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
// shallowRef: Vue doesn't make every record reactive, and a new array loads new records.
const records = shallowRef([]);
fetch('/api/orders').then((r) => r.json()).then((list) => (records.value = list));
const options = computed(() => ({ title: 'Orders', data: records.value }));
</script>
<template>
<div style="height: 480px"><DataGrid :options="options" /></div>
</template>Angular
import { Component, OnInit, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { DataGridComponent, DataGridOptions } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-orders',
imports: [DataGridComponent],
template: `<eight-data-grid [options]="options" style="height: 480px" />`,
})
export class Orders implements OnInit {
private http = inject(HttpClient);
options: DataGridOptions = { title: 'Orders', data: [] };
ngOnInit() {
this.http.get<Record<string, unknown>[]>('/api/orders').subscribe((data) => {
this.options = { title: 'Orders', data }; // a new object mounts the grid with the records
});
}
}Arrays of 4,096 or more objects are packed into columns in short slices before they go to the Worker, so the page keeps responding while a large array is copied. For the fastest start with very large data, pass columns and transferColumns: true.
Files
Pass file to open a File when the grid mounts, or call openFile(file, options) later. In the grid's own page the user picks a file with Open file. openFile takes delimiter and textColumns (CSV columns read as text, by letter or index) for CSV, and chooseSource: false to skip the chooser a workbook with several sheets or tables otherwise shows.
- Formats: XLSX, XLSM and XLTX workbooks, CSV, TSV and TXT text files.
- Workbooks: the grid opens the workbook's first table, or its first sheet when it has no tables. Source chooses another table or worksheet, and for a worksheet the range and whether its first row holds the headers.
- CSV: the delimiter is detected; Source can change it and read chosen columns as text, so codes such as
00123keep their zeros. - Streaming: files are read in a Worker through slices of the file, never as one buffer.
JavaScript
import { mountTable } from '@8sheets/data-grid';
const grid = await mountTable(document.querySelector('#grid'), { title: 'Your file' });
document.querySelector('input[type=file]').addEventListener('change', async (event) => {
const [file] = event.target.files;
if (file) await grid.openFile(file);
});React
import { useRef } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
const options = { title: 'Your file' };
export function FileViewer() {
const ref = useRef(null);
return (
<>
<input type="file" accept=".xlsx,.xlsm,.xltx,.csv,.tsv,.txt"
onChange={(e) => e.target.files[0] && ref.current.openFile(e.target.files[0])} />
<div style={{ height: 480 }}><DataGrid ref={ref} options={options} /></div>
</>
);
}Vue
<script setup>
import { ref } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
const options = { title: 'Your file' };
const dataGrid = ref(null);
const open = (e) => e.target.files[0] && dataGrid.value.openFile(e.target.files[0]);
</script>
<template>
<input type="file" accept=".xlsx,.xlsm,.xltx,.csv,.tsv,.txt" @change="open" />
<div style="height: 480px"><DataGrid ref="dataGrid" :options="options" /></div>
</template>Angular
import { Component, ViewChild } from '@angular/core';
import { DataGridComponent } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-file-viewer',
imports: [DataGridComponent],
template: `
<input type="file" accept=".xlsx,.xlsm,.xltx,.csv,.tsv,.txt" (change)="open($event)" />
<eight-data-grid #grid [options]="{ title: 'Your file' }" style="height: 480px" />`,
})
export class FileViewer {
@ViewChild('grid') grid!: DataGridComponent;
open(event: Event) {
const file = (event.target as HTMLInputElement).files?.[0];
if (file) this.grid.openFile(file);
}
}Sheets and tables of a workbook
getSources() lists the sheets and tables of the open file, setSource(index, { range, header }) shows another one, and getSource() says what the grid shows (its kind, title, file name, range, whether it is editable and whether it was changed).
await grid.openFile(file, { chooseSource: false });
const sources = grid.getSources(); // [{ index: 0, name: 'Sales', range: 'A1:F61', whole: false, header: true }, …]
const sheet = sources.find((s) => s.whole);
if (sheet) await grid.setSource(sheet.index, { range: 'A3:F200', header: true });
console.log(grid.getSource()); // { kind: 'file', title: 'Sales', fileName: 'q3.xlsx', dirty: false, … }
Replace the records
setData(data, { fields, title, editable, storageKey }) shows other records in the same grid; options left out keep their mount values, and the view starts over. refresh() draws them again.
JavaScript
const grid = await mountTable(document.querySelector('#orders'), { title: 'Orders', data: [] });
document.querySelector('#year').addEventListener('change', async (e) => {
const rows = await (await fetch(`/api/orders?year=${e.target.value}`)).json();
await grid.setData(rows, { title: `Orders ${e.target.value}` });
});React
// A new `data` array remounts the grid. To keep the grid and its options, call setData instead:
const ref = useRef(null);
async function showYear(year) {
const rows = await (await fetch(`/api/orders?year=${year}`)).json();
await ref.current.setData(rows, { title: `Orders ${year}` });
}
// <DataGrid ref={ref} options={options} />Vue
<script setup>
import { DataGrid } from '@8sheets/data-grid-vue';
import { ref } from 'vue';
const options = { title: 'Orders', data: [] };
const dataGrid = ref(null);
async function showYear(year) {
const rows = await (await fetch(`/api/orders?year=${year}`)).json();
await dataGrid.value.setData(rows, { title: `Orders ${year}` });
}
</script>
<template>
<button @click="showYear(2026)">2026</button>
<div style="height: 480px"><DataGrid ref="dataGrid" :options="options" /></div>
</template>Angular
// template: <eight-data-grid #grid [options]="options" />
@ViewChild('grid') grid!: DataGridComponent;
async showYear(year: number) {
const rows = await (await fetch(`/api/orders?year=${year}`)).json();
await this.grid.setData(rows, { title: `Orders ${year}` });
}Loading large data
Opening a large file, switching to another sheet, packing a large array, a server's first block and building a pivot are loads. A load that takes longer than 150 ms shows a panel over the grid with what it is doing, a progress bar and Cancel (or Escape). The bar is exact for CSV (bytes read) and XLSX (cells read against the sheet's recorded size), and indeterminate when the size isn't known. Cancelling keeps the records that were shown before, and the call that started the load rejects with an AbortError.
Your code sees the same through isLoading(), cancelLoad() and three events: loadStart ({ task, label }), loadProgress ({ task, records, loaded, total, fraction }, at most ten times a second) and loadEnd ({ task, label, status, error, records, duration }, with status done, cancelled or failed).
JavaScript
const status = document.querySelector('#status');
const grid = await mountTable(document.querySelector('#grid'), {
title: 'Your file',
onLoadProgress: (e) => (status.textContent = e.fraction == null ? `${e.records ?? 0} records…` : `${Math.round(e.fraction * 100)} %`),
onLoadEnd: (e) => (status.textContent = e.status === 'done' ? `${e.records} records in ${Math.round(e.duration)} ms` : e.status),
});
document.querySelector('#stop').addEventListener('click', () => grid.cancelLoad());
try {
await grid.openFile(file);
} catch (err) {
if (err.name !== 'AbortError') throw err; // a cancelled load is not an error
}React
const [progress, setProgress] = useState(null);
<DataGrid
ref={ref}
options={options}
onLoadStart={(e) => setProgress({ label: e.label, fraction: 0 })}
onLoadProgress={(e) => setProgress((p) => ({ ...p, fraction: e.fraction }))}
onLoadEnd={() => setProgress(null)}
/>
// {progress && <button onClick={() => ref.current.cancelLoad()}>Stop {progress.label}</button>}Vue
<DataGrid
ref="dataGrid"
:options="options"
@load-start="(e) => (progress = { label: e.label, fraction: 0 })"
@load-progress="(e) => (progress.fraction = e.fraction)"
@load-end="progress = null"
/>
<!-- <button v-if="progress" @click="dataGrid.cancelLoad()">Stop {{ progress.label }}</button> -->Angular
// template: <eight-data-grid #grid [options]="options" (loadStart)="label = $event.label" (loadProgress)="fraction = $event.fraction" (loadEnd)="label = null" />
// @if (label) { <button (click)="grid.cancelLoad()">Stop {{ label }}</button> }
label: string | null = null;
fraction: number | null = null;An editable copy
Local data is read-only unless you ask for editing. editable: true makes the records editable from the start; allowEdit: true adds an Edit copy button that turns a read-only view into a private copy, as enableEditing() does from code. getSource().dirty says whether the copy was changed. Edits stay in the copy until the user exports it. See Editing.
Limits
- One grid shows one table of records. A workbook's other sheets stay available through Source, one at a time.
- An XLSX or PDF export holds at most 1,048,575 records, Excel's sheet limit; CSV has no limit.
- Packing into columns applies to
string,numberandbooleanfields; other arrays go to the Worker as they are.