- Data Grid docs
- Developers
Framework wrappers
The React, Vue and Angular components of the Data Grid, their props, events and refs, and how options reach the grid.
@8sheets/data-grid-react, @8sheets/data-grid-vue and @8sheets/data-grid-angular each give you a <DataGrid> component (<eight-data-grid> in Angular). They mount the grid, pass it your options as they are, turn its events into your framework's events, give you every method of the grid through a ref, and destroy it when the component goes away. Every option of the API works through them, including functions such as detailRenderer, renderers and every on… callback.
At a glance
| React | Vue | Angular | |
|---|---|---|---|
| Package | @8sheets/data-grid-react | @8sheets/data-grid-vue | @8sheets/data-grid-angular |
| Versions | React 18 and 19 | Vue 3.4 and later | Angular 17 and later, zone.js or zoneless |
| Options | options prop | :options | [options] |
| Events | props: onStateChange, onBeforeEdit, onLoadStart… | kebab-case listeners: @state-change, @before-edit, @load-start… | outputs: (stateChange), (beforeEdit), (loadStart)… |
| Data change | onChange | @change | (gridChange) |
| Mounted | onReady(grid) | @ready | (ready) |
| Failed | onError(err) | @error | (gridError) |
| Methods | ref.current.sortBy(…): every method; they throw before onReady | template ref: every method; those returning a promise wait until the grid is ready, plus whenReady() | the component: every method, run outside the zone; they throw before ready |
| Server rendering | renders an empty <div>, mounts in an effect | mounts in onMounted | mounts in afterNextRender |
The handle has every method of the mounted grid except destroy, on and off: the component owns the grid, and its event props or listeners survive a remount. grid on the handle is the mounted grid itself, null before it has mounted. "Failed" covers a mount that failed and an action inside the grid that failed; the grid also shows its message.
A cancellable event (beforeEdit, editStart, rowDoubleClick…) is cancelled with e.preventDefault() in every framework. Returning false works in React and in options, but not through Vue's emit.
How options are followed
- A changed
chromeis applied in place withsetChrome. - Any other changed option mounts the grid again with the new options. Its view starts afresh, so keep it with
storageKey, or withgetStateandsetState. datais compared by identity: pass a new array to load new records, the same array to keep the grid. Other options are compared by value, and functions inside them are kept from the mount.- The component fills its container, so the container needs a height.
A complete component
The same order list in each framework: a grid with row selection, a change log, a cancellable edit check, and a button that downloads the selected orders.
JavaScript
import { mountTable } from '@8sheets/data-grid';
const button = document.querySelector('#export');
const grid = await mountTable(document.querySelector('#orders'), {
title: 'Orders',
data: orders,
editable: true,
rowSelection: 'multiple',
onChange: (change) => console.log(change.action, change.source),
onSelectionChange: (s) => (button.disabled = !s.count),
onBeforeEdit: (e) => {
if (e.cells.some((c) => c.field === 'Units' && Number(c.value) < 0)) e.preventDefault();
},
});
button.onclick = () => grid.download('xlsx', { selected: true });React
import { useMemo, useRef, useState } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
export function Orders({ orders }) {
const ref = useRef(null);
const [count, setCount] = useState(0);
const options = useMemo(() => ({ title: 'Orders', data: orders, editable: true, rowSelection: 'multiple' }), [orders]);
return (
<>
<button disabled={!count} onClick={() => ref.current.download('xlsx', { selected: true })}>Export {count}</button>
<div style={{ height: 480 }}>
<DataGrid
ref={ref}
options={options}
onChange={(change) => console.log(change.action, change.source)}
onSelectionChange={(s) => setCount(s.count ?? 0)}
onBeforeEdit={(e) => {
if (e.cells.some((c) => c.field === 'Units' && Number(c.value) < 0)) e.preventDefault();
}}
onError={(err) => console.error(err)}
/>
</div>
</>
);
}Vue
<script setup>
import { computed, ref } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
const props = defineProps({ orders: Array });
const options = computed(() => ({ title: 'Orders', data: props.orders, editable: true, rowSelection: 'multiple' }));
const dataGrid = ref(null);
const count = ref(0);
function checkUnits(e) {
if (e.cells.some((c) => c.field === 'Units' && Number(c.value) < 0)) e.preventDefault();
}
</script>
<template>
<button :disabled="!count" @click="dataGrid.download('xlsx', { selected: true })">Export {{ count }}</button>
<div style="height: 480px">
<DataGrid
ref="dataGrid"
:options="options"
@change="(c) => console.log(c.action, c.source)"
@selection-change="(s) => (count = s.count ?? 0)"
@before-edit="checkUnits"
@error="(err) => console.error(err)"
/>
</div>
</template>Angular
import { Component, Input, ViewChild } from '@angular/core';
import { DataGridChange, DataGridComponent, DataGridOptions } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-orders',
imports: [DataGridComponent],
template: `
<button [disabled]="!count" (click)="grid.download('xlsx', { selected: true })">Export {{ count }}</button>
<eight-data-grid
#grid
[options]="options"
(gridChange)="changed($event)"
(selectionChange)="count = $event.count ?? 0"
(beforeEdit)="checkUnits($event)"
(gridError)="failed($event)"
style="height: 480px" />`,
})
export class Orders {
@ViewChild('grid') grid!: DataGridComponent;
count = 0;
options: DataGridOptions = {};
@Input() set orders(data: Record<string, unknown>[]) {
this.options = { title: 'Orders', data, editable: true, rowSelection: 'multiple' };
}
changed(change: DataGridChange) {
console.log(change.action, change.source);
}
checkUnits(e: { cells: { field: string; value: unknown }[]; preventDefault(): void }) {
if (e.cells.some((c) => c.field === 'Units' && Number(c.value) < 0)) e.preventDefault();
}
failed(err: unknown) {
console.error(err);
}
}Framework notes
- React: handlers are always called from the latest render, so an inline arrow function never remounts the grid. In the Next.js App Router, use the component from a client component. A component inside
detailRendererneeds its own root (see Master/detail). - Vue: keep records in a
shallowRef, so Vue doesn't make each record reactive. The template ref has every method of the grid;useDataGrid()returns{ dataGrid, grid }, the template ref and the mounted grid, andwhenReady()on the ref resolves with the grid. - Angular: serve
@8sheets/data-gridas static files (see Getting started). The outputs areready,gridChangeandgridError, notchangeanderror, which are DOM events that bubble from the grid's own inputs. The grid runs outside Angular's zone and its outputs re-enter it, so prefer outputs toon…callbacks inoptions; a callback inoptionsruns outside the zone, so wrap the state changes it makes inNgZone.run.
Without a package
Licence holders find the same components in the source download, under integrations/react/data-grid/, integrations/vue/data-grid/ and integrations/angular/data-grid/, each with a README and an example app. They import the grid from src/table-view/index.js through one relative path.