Cell and Row Notes

GridNotesPlugin adds metadata notes without changing source rows. Every note is addressed by a stable host row ID and, for cell notes, a column prop. Sorting, filtering, pinning, grouping, clipboard values, and CSV output therefore remain independent from note content.

Configure the plugin

import {
  GridNotesPlugin,
  InMemoryGridNoteAdapter,
} from '@revolist/revogrid-pro';

const adapter = new InMemoryGridNoteAdapter();

grid.plugins = [GridNotesPlugin];
grid.gridNotes = {
  adapter,
  getRowId: row => row.id,
  getRowLabel: row => row.status,
  getCurrentUser: () => ({
    id: session.user.id,
    name: session.user.name,
    avatarUrl: session.user.avatarUrl,
  }),
  mentions: {
    search: (query, signal) => directory.searchUsers(query, { signal }),
  },
  can: ({ action, target, user }) => permissions.can(action, target, user),
  excel: { includeNotesSheet: true },
};

getRowId is required. It must be pure, stable, and globally unique across body and pinned row stores. A visual row index is not a valid ID. Duplicate visual presentations of the same authored row should resolve to the same ID; synthetic group and subtotal rows should not receive an authored ID.

getRowLabel is optional and controls the human-readable value displayed in a note title. Use it to bind a field such as status; the stable getRowId value is never shown in the popover.

The bundled in-memory adapter is a reference implementation for demos and tests. Production applications should implement GridNoteStorageAdapter against their API. Bulk loadSummaries() responses contain marker metadata and a 120-character excerpt only. Full bodies come from getNote(), while version bodies are paged through listVersions().

Set GridNoteUser.avatarUrl on authors and users returned by the mention directory to show their image beside their name in note metadata and mention suggestions. If an image cannot load, the plugin retains an accessible initials avatar, using GridNoteUser.color when supplied.

Interaction

• Open the row context menu for Add cell note or Add row note.
• Press Shift+F2 on the focused cell.
• Select a coloured corner marker without entering cell edit mode.
• Select the row-gutter bar or dot to open the row note and the other cell notes on that row.
• Save with Ctrl+Enter or Command+Enter.

The portalled dialog closes on Escape, outside pointer interaction, or when its virtualized anchor disappears. Unsaved text is retained in local storage and dirty close attempts use confirmDiscard.

Selecting Delete opens a confirmation panel inside that same dialog. It does not call the browser-native confirmation API.

Adapter concurrency

upsert, delete, and restoreVersion receive an idempotent mutation ID and expected version. An adapter should throw GridNoteConflictError when the current version changed. Restore creates a new current version with restoredFromVersionId; it never rewinds or mutates the append-only log.

Empty text is treated as a confirmed delete. Transient saves retry with jittered exponential backoff, pause while the browser is offline, and clear the persisted draft only after success.

Severity filter and export

The context menu includes a multi-select Filter by note severity submenu. Matching is row-wide: a row remains when its row note or any cell note has a selected severity. The plugin applies its own trimmed-state category, so ordinary filters keep their state.

When ExportExcelPlugin is also installed and excel.includeNotesSheet is true, XLSX output gains a Notes worksheet. It contains one row per current note, including target identity, severity, body, mentions, author, timestamps, and version count. Clipboard and CSV values are unchanged.

Events

Listen for gridnotechange, gridnotemention, gridnoteconflict, gridnoteerror, and gridnotefilterchange. Mention events contain only users introduced relative to the previous version, including a restore that reintroduces a mention.