Push live values
Push live values into cells by row id with updateCells, without a full data replacement, and control how a sorted view reacts.
updateCells writes values into the grid by row id. Use it for live feeds that update many cells per second. Every call needs a source: "stream" for a push, "edit" for a user edit.
Click the Change % header to sort: with Auto-sort off, rows hold their position as new values stream in and a "Re-sort" bar appears once the order goes stale; with Auto-sort on, the grid re-sorts on every tick (4/s).
Write patches
Address each write by the getRowId value and the column id. Render the feed component inside DataGridProvider, next to DataGridRoot:
import { useEffect } from "react";
import {
useDataGridActions,
type CellPatch,
} from "@/components/data-grid/data-grid";
type Quote = { symbol: string; price: number };
export function TickerFeed({ url }: { url: string }) {
const actions = useDataGridActions();
useEffect(() => {
const socket = new WebSocket(url);
socket.onmessage = (event: MessageEvent<string>) => {
const quotes = JSON.parse(event.data) as Quote[];
const patches: CellPatch[] = quotes.map((q) => ({
rowId: q.symbol,
columnId: "price",
value: q.price,
}));
actions.updateCells(patches, { source: "stream" });
};
return () => socket.close();
}, [actions, url]);
return null;
}One call is one batch. The grid applies all patches together and calls onDataChange once, with one update operation per touched row. Rows you do not patch keep their object identity and do not render again. The grid skips a patch for an unknown row id. To add a row to a local data array, pass a new array. With useDataGridServerRows, call server.reshape() after the server reports the row.
A call with source: "stream" takes at most 100,000 patches. The grid skips the patches after the limit. A stream deleteRows call takes at most 100,000 ids under the same rule.
A hidden column takes patches like a visible one. In controlled mode, pass the array that onDataChange gives you back as data unchanged. The grid recognizes its own array and keeps the sort, filter, and search results.
A call with source: "stream" writes into a readOnly grid and into read-only columns and rows. Another source, such as "edit", keeps every read-only check.
To patch several columns of one row at once, call actions.updateRows([{ rowId: "AAPL", changes: { price: 214.5 } }]). Each entry in changes becomes one patch. The options are the same as for updateCells.
Sorted and filtered views
If a patch changes a value that the sort or filter reads, the row keeps its position and the grid sets a stale flag. Read the flag with useDataGridViewStale and give the user a control to re-sort. Render it inside the provider:
import {
useDataGridActions,
useDataGridViewStale,
} from "@/components/data-grid/data-grid";
export function ReSortBar() {
const actions = useDataGridActions();
const viewStale = useDataGridViewStale();
if (!viewStale) return null;
return <button onClick={() => actions.reconcileView()}>Re-sort</button>;
}reconcileView() clears the flag. A change of sort or filter does the same. An edit, paste, fill, or cell clear that touches such a column also marks the view stale.
The reorder option of UpdateCellsOptions takes an UpdateCellsReorder value and sets this behavior per call, for example { reorder: "immediate" }:
| Value | Behavior |
|---|---|
"defer" (default) | The value changes, the row holds its position, and viewStale becomes true. |
"immediate" | The grid moves the patched rows to their new positions in the same call. |
"frame" | The value changes at once. The next animation frame moves every row patched since the last one. |
"never" | The value changes and viewStale stays false. |
If no patched column feeds the active sort or filter, "defer" and "frame" act as "never". reconcileView() runs a pending "frame" move at once.
"immediate" keeps the order when every patched row still sits between its neighbors. Otherwise it puts the patched rows at the positions a full sort gives them.
With sortMode="server" or filterMode="server", the server orders the rows. A push marks the row stale and the hook can refetch. See Push into a server-ordered view.
Flash changed cells
The grid flashes cells on its own only after a fill. A push does not flash. To flash the cells that a push wrote, pass { flash: true }, as in actions.updateCells(patches, { source: "stream", flash: true }). updateRows takes it too. The call flashes the cells it applied at once. A held batch flashes after settled. Cells of hidden columns do not flash.
actions.flashCells(cells, durationMs?) flashes any cells without a write. Each cell is a CellRef with rowId and columnId. flashCells changes no data and adds no history entry. durationMs sets how long the cell keeps data-flash, 1400 by default. --grid-flash-duration, --grid-flash-color, and --grid-flash-intensity style the flash. See Style contract.
Undo and save
A batch with source: "stream" is not recorded by the history add-on, and onSave never receives it. A push into a row with a save in flight is held with reason saving and applies once the row's save settles. A later push to the same cell replaces it.
To make a batch undoable, pass { source: "edit" }. It reaches onSave. To record streams without that, add the source to the defaults of the history add-on:
const history = useDataGridHistory<Row>({
recordSources: (defaults) => [...defaults, "stream"],
});What stays in place
A batch without reorder: "immediate" does not move the selection, the active cell, or an open editor. An immediate re-sort moves the open edit with its row.
If a value fails validate, the grid skips it and applies the rest of the batch. onValidationError then reports the skipped values with source: "stream". See Edit and validation events. When the producer already checked the values, set skipValidation: true.
A batch into a column with an async schema changes nothing until the schema answers. The accepted cells then commit together as one onDataChange. A write that changes the rows supersedes the held batch, such as an edit or a row operation. So does a rebuild of the view, such as a sort change. The grid drops the late answer. If every cell fails, the batch commits nothing. See Validation.
Read the verdict
updateCells and updateRows return an UpdateCellsVerdict with applied, skipped, pending, and settled. Read a push verdict lists the skip reasons.
Related
- Push into a server-ordered view: stale rows and reshape
- Show presence: paint the selections of peers
- Data change events: the operations that a change reports
- Undo and redo: the history add-on
- State and view index: row ids and view indices
Select server rows
Keep checked rows across pages, select every matching row of a server result, and send the selection to your API as ids or as a spec.
Push into a server-ordered view
Mark pushed rows as stale, reshape the view from the server, and delete rows that the server removed, when the server sorts or filters the rows.