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.
| Symbol | Purpose | Guide |
|---|---|---|
useDataGridPresence | Returns the plugin and the functions that set highlights | Show presence |
setPresenceHighlights | Replaces the whole list of highlights | Show presence |
removePresenceHighlight | Removes one highlight by id | Show presence |
clearPresenceHighlights | Removes every highlight | Show presence |
toPresenceEntries | Turns a local selection into the row-id range entry to send to peers | Broadcast your selection |
| Highlight shapes | The cell, row-id range, and view range entries | Show 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
rowIdorcolumnIdis empty, not a string, or longer than 256 characters. - A range entry with empty
rowIdsorcolumnIds. - A range entry with a
rowIdsorcolumnIdsentry that is empty, not a string, or longer than 256 characters. - A view entry without a finite
x,y,width, andheight. - An entry whose
idis 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.
| Shape | Coordinates | Resolved against |
|---|---|---|
RowIdPresenceHighlight | rowId, columnId | The row ids and column ids of the receiving grid |
RowIdRangePresenceHighlight | rowIds, columnIds | The row ids and column ids of the receiving grid |
ViewRangePresenceHighlight | range | Nothing: 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]} />;
}Related
- Show presence: wiring, row ids, and rendering.
- Broadcast your selection: send your own selection to peers.
- Selection and cell events: the payload of
onSelectionChange.