gridcn2.0.0
Rows and live data

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.

A push (updateCells, updateRows, or deleteRows with source: "stream") writes a value into a grid whose order your server decides. The grid cannot move the row. It marks the row stale and lets the hook refetch. See Push live values for the push itself.

This page applies with sortMode="server" or filterMode="server". Your server orders and filters the rows. The grid never tests a pushed row against the sort or filter.

sort, filter, search and paging are all server-side
Loading…
Name
Email
Role
Score
Page 1

Mark stale rows

A push that changes a column the server reads leaves the row where it is. The grid marks the row as a stale row and sets viewStale. The server reads these columns:

  • With sortMode="server": the columns of the active sort.
  • With filterMode="server": the columns of the filter. While the search text is not empty, every column.

A stale row carries the attribute data-row-stale. The grid ships no style for it. This grid pushes prices from a socket, dims stale rows, and reshapes one second after a push:

"use client";

import { useEffect } from "react";
import {
  DataGridBody,
  DataGridHeader,
  DataGridProvider,
  DataGridRoot,
  defineColumns,
  useDataGridActions,
} from "@/components/data-grid/data-grid";
import { useDataGridServerRows } from "@/components/data-grid-server/data-grid-server";

type Order = { id: string; price: number };

const columns = defineColumns<Order>()([
  { id: "price", header: "Price", accessorKey: "price", type: "number" },
]);

function PriceFeed() {
  const actions = useDataGridActions();
  useEffect(() => {
    const socket = new WebSocket("wss://api.example.com/prices");
    socket.onmessage = (event: MessageEvent<string>) => {
      const { id, price } = JSON.parse(event.data) as Order;
      actions.updateCells(
        [{ rowId: id, columnId: "price", value: price }],
        { source: "stream" },
      );
    };
    return () => socket.close();
  }, [actions]);
  return null;
}

export function OrdersGrid() {
  const server = useDataGridServerRows<Order>({
    mode: "scroll",
    fetchRows: async ({ spec, start, end, signal }) => {
      const response = await fetch("/api/orders/query", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ spec, start, end }),
        signal,
      });
      const answer = await response.json();
      return { rows: answer.rows, totalRowCount: answer.total };
    },
  });

  return (
    <DataGridProvider {...server.providerProps} columns={columns}>
      <PriceFeed />
      <DataGridRoot
        {...server.rootProps}
        className="h-96 [&_[data-row-stale]]:text-muted-foreground"
      >
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
    </DataGridProvider>
  );
}

The reorder option sets the behavior per call:

ValueBehavior
"defer" (default)The value changes in place and the row turns stale.
"immediate"As "defer", and the grid asks useDataGridServerRows to reshape on the next frame. Without the hook, the rows stay marked and development builds warn once.
"never"The value changes in place and no row turns stale.

A row stops being stale when:

  • Your data delivers a different row object for its id.
  • Its id leaves data, for example by a page change, an eviction, or a delete.
  • The sort, filter, or search text changes.

Reshape the view

reconcileView() asks useDataGridServerRows to reshape and keeps the marks until the answer delivers the rows again. A sequential source sends no request while the rendered rows plus overscan end beyond 10 blocks. The marks then stay until refresh() or a spec change. Without the hook, it clears the marks. When the view turns stale, the live region reads labels.grid.viewStale once, at most once every 30 seconds, in every data mode.

A reshape is a refresh() that the hook runs, so the server places the rows again. While the spec has a sort or a filter, the hook reshapes on its own after a push. A stale row starts one throttled refresh() after reshapeDelayMs (milliseconds, at least 250, default 1000). Pass false to turn it off.

A push delete and server.reshape() refresh on the next frame, or after the delay when it is set. A sequential source skips that refresh while the rendered rows plus overscan end beyond 10 blocks. Call server.refresh() there. With reshapeDelayMs: false, a stale row waits for reshape(), refresh(), or a spec change.

Delete and insert rows

To remove a row that the server deleted, push a delete:

actions.deleteRows(["AAPL"], { source: "stream" });

A push delete skips onBeforeDeleteRows, onSave, and the undo history. It unchecks the row, and the other checked rows stay checked. The active cell stays on its row, and a cell range collapses onto it. If the deleted row held the active cell, the active cell clears. One push delete takes at most 100,000 ids and skips the rest. The server owns the row count. Until the reshape runs, the count can be off by the deleted rows.

The grid cannot place an inserted row, because it does not know the position. When the server reports a new row, call server.reshape().

A push to a row that is not loaded is skipped with reason unknown-row, and the next block brings the server value. A push made while a request is open stays: the cells that the push wrote stay on the row that the answer delivers.

On this page