gridcn2.0.0
Add-on optionsServer

Presence options

Look up the options and result of useDataGridPresence, the three highlight shapes, and the guards that tell the shapes apart.

useDataGridPresence returns a plugin that paints the selections of remote users into the grid, and the functions that set the highlights. Call it once for each grid, above the grid (DataGrid or DataGridProvider). Each call creates its own highlight store and plugin. Pass the plugin of that call to the grid. The functions of another call paint nothing. The steps are on Show presence.

SymbolPurposeGuide
useDataGridPresenceReturns the plugin and the functions that set highlightsShow presence
setPresenceHighlightsReplaces the whole list of highlightsShow presence
removePresenceHighlightRemoves one highlight by idShow presence
clearPresenceHighlightsRemoves every highlightShow presence
toPresenceEntriesTurns a local selection into the row-id range entry to send to peersBroadcast your selection
Highlight shapesThe cell, row-id range, and view range entriesShow presence

Options

Prop

Type

maxRects defaults to MAX_RESOLVED_RECTS, which is 1024. It caps the rectangles that one RowIdRangePresenceHighlight entry paints, one for each contiguous fragment. The overlay drops the excess. After the overlay commits, it calls onExcessRects({ entry, kept, total }) once each time the kept and total of an entry change. The argument has the type ExcessRectsContext. The call runs outside the render, so it can set React state. Development builds also warn once for each entry.

Result

Prop

Type

setPresenceHighlights replaces the whole list, so each call carries the full set of entries. removePresenceHighlight(id) removes the entry with that id. If no entry matches, it does nothing. clearPresenceHighlights() removes every entry.

setPresenceHighlights drops malformed entries:

  • A value that is no object.
  • A cell entry whose rowId or columnId is empty, not a string, or longer than 256 characters.
  • A range entry with empty rowIds or columnIds.
  • A range entry with a rowIds or columnIds entry that is empty, not a string, or longer than 256 characters.
  • A view entry without a finite x, y, width, and height.
  • An entry whose id is missing, not a string, or longer than 256 characters.
  • An entry past the first 1000.

A payload that is not an array clears every highlight. An id list of more than 10,000 ids keeps the first 10,000.

The hook repairs two fields. A label that is no string is removed, and a label of more than 64 characters is cut. A color that is no string, or longer than 128 characters, paints as var(--color-primary).

Development builds warn once for each dropped entry.

All three functions re-render the overlay layer. They re-render no row and no cell. To read the highlights in another component, pass storeApi (type PresenceStoreApi) to useDataGridPresenceHighlights(storeApi). That hook re-renders only its caller.

Highlight shapes

A highlight entry has one of three shapes. Every shape needs a unique id, a color, and takes an optional label.

ShapeCoordinatesResolved against
RowIdPresenceHighlightrowId, columnIdThe row ids and column ids of the receiving grid
RowIdRangePresenceHighlightrowIds, columnIdsThe row ids and column ids of the receiving grid
ViewRangePresenceHighlightrangeNothing: the view indices paint as given. A receiver with another sort or filter paints wrong cells.

Single cell

A single cell is a RowIdPresenceHighlight:

Prop

Type

Row-id range

A row-id range is a RowIdRangePresenceHighlight:

Prop

Type

View range

A view range is a ViewRangePresenceHighlight:

Prop

Type

The overlay drops a row that a filter hides. For a single cell with a hidden or unknown column, it drops the entry and warns once in development. For a range, it drops the missing columns and warns once. A range with no resolved row or no resolved column paints nothing. A filter that splits a range paints one rect per contiguous fragment. An entry that carries both rowId and rowIds paints as a single cell.

color takes any CSS color or token. An invalid color or an undefined token paints as var(--color-primary). The chip text is black on light colors and white on dark ones. Set --presence-label-foreground for one fixed chip text color.

Guards

isRowIdPresenceHighlight(entry) and isRowIdRangePresenceHighlight(entry) narrow a PresenceHighlightEntry to the cell form and the range form. A rowId must be a non-empty string. rowIds must be an array of strings.

Example

This sample paints one remote cell and one remote range:

import { useEffect } from "react";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import {
  useDataGridPresence,
} from "@/components/data-grid-presence/data-grid-presence";

type Row = { id: string; name: string; city: string };

const rows: Row[] = [
  { id: "r1", name: "Ada", city: "London" },
  { id: "r2", name: "Alan", city: "Wilmslow" },
];
const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
  { id: "city", header: "City", accessorKey: "city" },
]);

export function PresenceGrid() {
  const { plugin, setPresenceHighlights } = useDataGridPresence();

  useEffect(() => {
    setPresenceHighlights([
      {
        id: "u1",
        color: "var(--color-primary)",
        label: "Ada",
        rowId: "r1",
        columnId: "name",
      },
      {
        id: "u2",
        color: "var(--color-destructive)",
        rowIds: ["r1", "r2"],
        columnIds: ["city"],
      },
    ]);
  }, [setPresenceHighlights]);

  return <DataGrid defaultData={rows} columns={columns} plugins={[plugin]} />;
}

On this page