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

Open the sales example

At a glance

ReactVueAngular
Package@8sheets/data-grid-react@8sheets/data-grid-vue@8sheets/data-grid-angular
VersionsReact 18 and 19Vue 3.4 and laterAngular 17 and later, zone.js or zoneless
Optionsoptions prop:options[options]
Eventsprops: onStateChange, onBeforeEdit, onLoadStart…kebab-case listeners: @state-change, @before-edit, @load-start…outputs: (stateChange), (beforeEdit), (loadStart)…
Data changeonChange@change(gridChange)
MountedonReady(grid)@ready(ready)
FailedonError(err)@error(gridError)
Methodsref.current.sortBy(…): every method; they throw before onReadytemplate 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 renderingrenders an empty <div>, mounts in an effectmounts in onMountedmounts 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 chrome is applied in place with setChrome.
  • Any other changed option mounts the grid again with the new options. Its view starts afresh, so keep it with storageKey, or with getState and setState.
  • data is 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 detailRenderer needs 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, and whenReady() on the ref resolves with the grid.
  • Angular: serve @8sheets/data-grid as static files (see Getting started). The outputs are ready, gridChange and gridError, not change and error, 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 to on… callbacks in options; a callback in options runs outside the zone, so wrap the state changes it makes in NgZone.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.