Highlighting Changes

Enterprise

Introduction

Change highlighting draws the eye to data that just moved — a price tick, a refreshed metric, a status that flipped. changeHighlight() watches your data and, whenever a cell’s value changes, briefly flashes that one cell, then fades it back.

It plugs into the grid’s cellStyleProvider slot and attaches to the grid so it can diff each update:

import { changeHighlight } from '@zengrid/enterprise/grid';

const flash = changeHighlight({ duration: 900 });

const grid = new Zengrid(el, {
  cellStyleProvider: flash,   // flash flags the changed cells
  columns,
});
flash.attach(grid);           // …and watches setData for changes

grid.setData(rows);           // first load — the baseline, nothing flashes
grid.setData(nextRows);       // every changed cell flashes

changeHighlight() is license-gated (it asserts the change-highlight feature). The default flash uses the bundled zg-cell-flash class, whose one-shot animation washes --zg-flash-color over the cell and fades to transparent over --zg-flash-duration.

How change detection works

The manager wraps setData, so detection is automatic: it snapshots the previous rows and, on the next setData, diffs them cell-by-cell. Snapshotting means it works even when you mutate the same row arrays in place and re-set them.

• Identity. By default a row is identified by its position, which is right for live feeds that keep row order. Pass getRowId to track a row by a stable key instead, so a value change still flashes even when the row is sorted to a new spot.
• What counts as a change. By default any value that isn’t Object.is-equal to the previous one. Override changed(prev, next) to ignore noise (rounding, say).
• In-place edits. If you mutate one cell and repaint it with updateCells instead of replacing the data, call flash.flashCells([{ row, col }]) to flag it yourself. See View Refresh for the repaint APIs.

Customising the flash

Everything about the highlight is configurable:

• flashClass — the CSS class(es) added while a cell flashes (default zg-cell-flash). Pass your own to restyle, or '' to rely on the others.
• flashStyle — inline styles applied while flashing; composes with flashClass.
• duration — how long (ms) the highlight stays before it’s removed (default 1000).
• directionClasses — for numeric changes, add an extra up / down class so a rise and a fall can flash different colours — the classic green-up / red-down ticker.

Auto on setDataUp / downManual flashCells

CodeDemoSplit

ResetRun ⌘⏎

The manager diffs each setData and flashes only the changed cells. Change duration, or lower the 6000 to make quieter ticks.

Types

interface ChangeHighlightOptions {
  flashClass?: string | string[];              // default 'zg-cell-flash'
  flashStyle?: Record<string, string | number>;
  duration?: number;                           // ms, default 1000
  getRowId?: (rowData: unknown[]) => string | number;
  changed?: (prev: unknown, next: unknown) => boolean;
  directionClasses?: { up?: string; down?: string };
}

interface CellChange { row: number; col: number } // display coords

function changeHighlight(options?: ChangeHighlightOptions): ChangeHighlight;

interface ChangeHighlight {
  attach(grid): void;              // watch the grid's setData for changes
  detach(): void;                  // restore setData, cancel pending flashes
  flashCells(cells: CellChange[]): void; // flag cells to flash manually
}

Notes

• Set it as cellStyleProvider and attach() it. The provider stamps the flash onto changed cells; attach() is what wires the automatic setData diffing.
• The baseline never flashes. The first setData establishes the reference; only changes on later updates flash.
• One provider slot. cellStyleProvider holds a single provider, so change highlighting and grid-wide cell styling can’t both occupy it at once — pick the one the grid needs.
• Positional columns. Like other cell providers, changes are keyed by column index; if you reorder columns at runtime, pass getRowId and key your own logic.

Next

• View Refresh — the repaint APIs that pair with flashCells.
• Styling Cells — static and rule-based cell styling.
• Row Data — replacing and updating the rows behind the grid.