gridcn2.0.0
Plugins

Plugin events

Learn when a plugin observer runs, what it receives, how a throw in it is handled, and how it writes data back to the grid.

A plugin observes data with its onDataChange member. The grid calls it for every change it applies. The source field of the change names the origin. Its values are "edit", "paste", "fill", "delete", "cut", "row-operation", "import", and "history" (undo and redo). The other values are "rollback", "merge", "id-swap", "stream", "replace", and "app".

Observing data changes

One change reaches its listeners in this order:

  1. The store write lands.
  2. Your own onDataChange prop runs.
  3. Your onSave prop runs. It never receives a change with the source "rollback", "stream", or "id-swap".
  4. Each plugin observer runs, in array order.

Observers receive every source, also "rollback", "merge", "id-swap", and "stream". When an observer reacts to user edits only, filter on change.source.

An observer receives (next, change, ctx):

  • next is the data array after this change.
  • change is the DataChange batch. Its ops hold one operation per changed row, and each operation carries a rowId.
  • ctx.api is the imperative handle of the grid.

This plugin reports the source and the row ids of every change:

"use client";

import { useEffect, useMemo, useRef } from "react";
import type { DataGridPlugin } from "@/components/data-grid/data-grid";

export function useAuditLog(
  report: (source: string, rowIds: string[]) => void,
): { plugin: DataGridPlugin } {
  const reportRef = useRef(report);
  useEffect(() => {
    reportRef.current = report;
  }, [report]);
  return useMemo(
    () => ({
      plugin: {
        name: "audit-log",
        onDataChange: (_next, change) => {
          reportRef.current(
            change.source,
            change.ops.map((op) => op.rowId),
          );
        },
      },
    }),
    [],
  );
}

The plugin reads report through a ref, so a new report function does not rebuild the plugin.

Errors in observers

When an observer runs, the change is already applied. An observer that throws logs a console warning. The remaining observers still run, and the grid never rolls the write back.

A throw in your own onDataChange prop differs. The grid runs onSave and all observers first, then rethrows that error.

Writing back

An observer writes through the public actions. ctx.api.actions.commitChange(change) applies a change batch to the grid.

The write emits its own change, and every observer sees it. That includes the observer that wrote. Guard the observer so that it does not write in a loop.

On a read-only grid, commitChange writes nothing and emits nothing, except for a change with source: "stream".

The undo and redo add-on uses this path. Its observer records each change. Its undo and redo commands apply the inverted batch through commitChange. An update with cells writes only those cells onto the current row.

On this page