1. Data Grid docs
  2. 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:

ShapeExampleNotes
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 00123 keep 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, number and boolean fields; other arrays go to the Worker as they are.