1. Data Grid docs
  2. Start here

Getting started

Install the Data Grid from npm or the source download, mount it in a page or a React, Vue or Angular app, and set up your bundler.

The Data Grid is one function, mountTable(element, options), which fills an element with a grid and returns a handle to it. The framework components wrap that function, so every option works the same way in all four.

Open the sales example

Install

JavaScript

npm i @8sheets/data-grid

React

npm i @8sheets/data-grid @8sheets/data-grid-react

Vue

npm i @8sheets/data-grid @8sheets/data-grid-vue

Angular

npm i @8sheets/data-grid @8sheets/data-grid-angular

The packages are free to install and evaluate. Using them in a product needs a licence; see Pricing. Licence holders also get the readable source in their download: src/table-view/index.js is the same entry point as the npm package.

Mount a grid

The element needs a height: the grid fills it and scrolls inside it. Each mount has its own Worker, search, selection and history, so several grids can share a page.

JavaScript

import { mountTable } from '@8sheets/data-grid';

const grid = await mountTable(document.querySelector('#orders'), {
  title: 'Orders',
  storageKey: 'orders',            // enables saved views
  fields: [
    { name: 'Order', type: 'number', format: '0' },
    { name: 'Region', type: 'string' },
    { name: 'Units', type: 'number' },
    { name: 'Price', type: 'number', format: '#,##0.00' },
    { name: 'Revenue', type: 'number', format: '#,##0.00', formula: '[@Units]*[@Price]' },
  ],
  data: await (await fetch('/api/orders')).json(),
  onChange: (change) => console.log(change.action),
});

// Group by region with a revenue total for each group.
await grid.setState({ ...grid.getState(), groups: [{ field: 'Region' }], total: { field: 'Revenue', agg: 'sum' } });

// Later, when the page goes away:
grid.destroy();

React

import { useMemo, useRef } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';

const fields = [
  { name: 'Order', type: 'number', format: '0' },
  { name: 'Region', type: 'string' },
  { name: 'Units', type: 'number' },
  { name: 'Price', type: 'number', format: '#,##0.00' },
  { name: 'Revenue', type: 'number', format: '#,##0.00', formula: '[@Units]*[@Price]' },
];

export function Orders({ orders }) {
  const ref = useRef(null);
  // `data` is compared by identity: a new array loads new records, the same array keeps the grid.
  const options = useMemo(() => ({ title: 'Orders', storageKey: 'orders', fields, data: orders }), [orders]);
  return (
    <div style={{ height: 480 }}>
      <DataGrid
        ref={ref}
        options={options}
        onChange={(change) => console.log(change.action)}
        onReady={(grid) => grid.setState({ ...grid.getState(), groups: [{ field: 'Region' }], total: { field: 'Revenue', agg: 'sum' } })}
      />
    </div>
  );
}

Vue

<script setup>
import { computed, shallowRef } from 'vue';
import { DataGrid, useDataGrid } from '@8sheets/data-grid-vue';

const props = defineProps({ orders: Array });
const fields = [
  { name: 'Order', type: 'number', format: '0' },
  { name: 'Region', type: 'string' },
  { name: 'Units', type: 'number' },
  { name: 'Price', type: 'number', format: '#,##0.00' },
  { name: 'Revenue', type: 'number', format: '#,##0.00', formula: '[@Units]*[@Price]' },
];
// `data` is compared by identity; keep large arrays out of deep reactivity.
const options = computed(() => ({ title: 'Orders', storageKey: 'orders', fields, data: props.orders }));
const { dataGrid, grid } = useDataGrid();

function onReady(g) {
  g.setState({ ...g.getState(), groups: [{ field: 'Region' }], total: { field: 'Revenue', agg: 'sum' } });
}
</script>

<template>
  <div style="height: 480px">
    <DataGrid ref="dataGrid" :options="options" @ready="onReady" @change="(c) => console.log(c.action)" />
  </div>
</template>

Angular

import { Component, Input } from '@angular/core';
import { DataGridChange, DataGridComponent, DataGridOptions, MountedDataGrid } from '@8sheets/data-grid-angular';

@Component({
  selector: 'app-orders',
  imports: [DataGridComponent],
  template: `<eight-data-grid [options]="options" (ready)="onReady($event)" (gridChange)="changed($event)" />`,
  styles: `eight-data-grid { height: 480px; }`,
})
export class Orders {
  @Input() set orders(data: Record<string, unknown>[]) {
    // A new object is a new mount; `data` is compared by identity.
    this.options = { title: 'Orders', storageKey: 'orders', fields: FIELDS, data };
  }
  options: DataGridOptions = {};

  onReady(grid: MountedDataGrid) {
    grid.setState({ ...grid.getState(), groups: [{ field: 'Region' }], total: { field: 'Revenue', agg: 'sum' } });
  }
  changed(change: DataGridChange) {
    console.log(change.action);
  }
}

const FIELDS = [
  { name: 'Order', type: 'number', format: '0' },
  { name: 'Region', type: 'string' },
  { name: 'Units', type: 'number' },
  { name: 'Price', type: 'number', format: '#,##0.00' },
  { name: 'Revenue', type: 'number', format: '#,##0.00', formula: '[@Units]*[@Price]' },
];

fields is optional for local data: without it the grid takes the field names from the records and infers their types. Give it when you want captions, number formats, calculated fields or field rules. A server source always needs it.

Methods and events

The mounted grid has a method for everything a user can do in it, from sortBy and setFilters to addRecords, openPivot and download, and it reports what happens through events such as stateChange, change, selectionChange and loadEnd. The interface takes the same paths, so an action fires the same events whether a user or your code did it. Every event has an on… option, and grid.on(name, handler) adds a handler and returns a function that removes it. setOptions({ … }) changes live options, such as rowSelection or a handler, without a new mount. The API reference lists them all.

JavaScript

const grid = await mountTable(el, { title: 'Orders', data: orders });

const stop = grid.on('stateChange', (e) => console.log('changed', e.changed));
await grid.sortBy('Revenue', { desc: true });
await grid.setOptions({ rowSelection: 'multiple' });
stop();

React

// The ref has every method of the grid (they throw before onReady); events are props.
const ref = useRef(null);
<DataGrid ref={ref} options={options} onStateChange={(e) => console.log('changed', e.changed)} />;
await ref.current.sortBy('Revenue', { desc: true });

Vue

<!-- The template ref has every method; events are kebab-case listeners. -->
<DataGrid ref="dataGrid" :options="options" @state-change="(e) => console.log('changed', e.changed)" />
<!-- await dataGrid.value.sortBy('Revenue', { desc: true }) -->

Angular

// The component has every method; events are outputs of the same name.
// template: <eight-data-grid #grid [options]="options" (stateChange)="log($event)" />
@ViewChild('grid') grid!: DataGridComponent;
async newestFirst() {
  await this.grid.sortBy('Revenue', { desc: true });
}

Bundlers

The grid finds its Worker and stylesheet next to its own modules, through new URL('./…', import.meta.url), so bundlers copy them into your build. The Worker is an ES module.

  • Vite: set worker: { format: 'es' }. Before Vite 8, also add optimizeDeps: { exclude: ['@8sheets/data-grid'] } (and the wrapper package you use): the older pre-bundling moves the modules away from their Worker.
  • webpack and Next.js: no settings. In the Next.js App Router, use the React component from a client component; the package is marked 'use client'.
  • Angular CLI: it doesn't copy files a module loads at run time, so @8sheets/data-grid-angular loads the grid from your static files. Add the package to the assets of your build target:
"assets": [
  { "glob": "**/*", "input": "node_modules/@8sheets/data-grid", "output": "8sheets-data-grid", "ignore": ["**/*.d.ts", "*.md", "package.json"] }
]

To serve it from another path, provide EIGHT_DATA_GRID_URL with the address of table-view/index.js.

  • No bundler: serve the package folder and import table-view/index.js from it.

Parts of the grid load on demand: a page that never opens an Excel file or exports a PDF never downloads that code.

Version

VERSION, exported by @8sheets/data-grid, is the release you run. Data Grid has its own changelog, separate from Spreadsheet's.

import { VERSION } from '@8sheets/data-grid';
console.log(VERSION); // "1.0.0"

Next