DataGridEventMap

Since v0.1.1

Maps event names to their detail payload types.

Used by grid.on() and addEventListener() for fully typed event handling. Plugins extend this map via module augmentation.

Example

// Recommended: grid.on() auto-unwraps the detail
const off = grid.on('cell-click', ({ field, value, row }) => {
  console.log(`Clicked ${field} = ${value}`);
});
off(); // unsubscribe

// addEventListener works too (useful for { once, signal, capture })
grid.addEventListener('cell-click', (e) => {
  console.log(e.detail.field);
}, { once: true });

Core Events

Property	Type	Description
cell-click	CellClickDetail<TRow>	Fired when a cell is clicked. Provides full context: row data, column config, cell element, and the original mouse event.
row-click	RowClickDetail<TRow>	Fired when a row is clicked (anywhere on the row). Use for row-level actions like opening a detail panel or navigating.
cell-activate	CellActivateDetail<TRow>	Fired when a cell is activated by Enter key or pointer click. Unified event for both keyboard and pointer activation.
cell-change	CellChangeDetail<TRow>	Fired after any data mutation — user edits, cascade updates, or API calls. This is an informational event for logging, auditing, or cascading updates to related fields. Check source to distinguish edit origins.
data-change	DataChangeDetail	Fired whenever the grid’s row data changes — new data assignment, row insertion/removal, or in-place mutations via updateRow(). Use to keep external UI (row counts, summaries, charts) in sync.
tbw-scroll	TbwScrollDetail	Fired when the grid’s viewport is scrolled vertically (rAF-batched). Use to trigger pagination, defer heavy cell content, dismiss overlays, or sync external UI to the grid’s scroll position.
sort-change	SortChangeDetail	Fired when the sort state changes — column header click, programmatic sort, or sort cleared. direction: 0 indicates the sort was removed.
column-resize	ColumnResizeDetail	Fired when a column is resized by the user dragging the resize handle. Use to persist column widths to user preferences or localStorage.
column-resize-reset	ColumnResizeResetDetail	Fired when a user-resized column is reset to its original configured width. Triggered by the column header context menu “Reset width” action.
column-state-change	GridColumnState	Fired when column state changes — reordering, resizing, visibility toggle, or sort changes. Use with getColumnState() / columnState setter for full state persistence.
render	RenderDetail	Fired once at the end of every render cycle, after all plugin afterRender hooks have run and ready() has resolved. v2.15.0+

Property Details

cell-click

grid.on('cell-click', ({ row, field, value, cellEl }) => {
  console.log(`Clicked ${field} = ${value}`);

  // Open a detail dialog for a specific column
  if (field === 'avatar') {
    showImagePreview(row.avatarUrl, cellEl);
  }
});

See also: CellClickDetail

---

row-click

grid.on('row-click', ({ row, rowIndex }) => {
  console.log(`Row ${rowIndex}: ${row.name}`);

  // Navigate to detail page
  router.navigate(`/employees/${row.id}`);
});

See also: RowClickDetail

---

cell-activate

Fired when a cell is activated by Enter key or pointer click. Unified event for both keyboard and pointer activation.

Call event.preventDefault() to suppress default behavior (e.g., inline editing).

grid.on('cell-activate', ({ row, field, trigger, cellEl }, event) => {
  // Custom editing for a specific column
  if (field === 'notes') {
    event.preventDefault();
    openRichTextEditor(row, cellEl);
  }

  console.log(`Activated via ${trigger}`); // 'keyboard' | 'pointer'
});

See also: CellActivateDetail · CellActivateTrigger

---

cell-change

grid.on('cell-change', ({ row, rowId, field, oldValue, newValue, source }) => {
  console.log(`${field}: ${oldValue} → ${newValue} (${source})`);

  // Cascade: recalculate total when quantity changes
  if (source === 'user' && field === 'quantity') {
    grid.updateRow(rowId, { total: newValue * row.price });
  }
});

See also: CellChangeDetail · UpdateSource

---

data-change

grid.on('data-change', ({ rowCount, sourceRowCount }) => {
  statusBar.textContent = `${rowCount} of ${sourceRowCount} rows`;
});

See also: DataChangeDetail

---

tbw-scroll

Fired when the grid’s viewport is scrolled vertically (rAF-batched). Use to trigger pagination, defer heavy cell content, dismiss overlays, or sync external UI to the grid’s scroll position.

For server-side pagination of large datasets, prefer the ServerSidePlugin — it handles block fetching out of the box.

// Infinite scroll
grid.on('tbw-scroll', ({ scrollTop, scrollHeight, clientHeight }) => {
  if (scrollTop + clientHeight >= scrollHeight - 200) loadMore();
});

// Defer heavy cell content (Angular @defer style)
grid.on('tbw-scroll', ({ scrollTop }) => {
  updateVisibleHeavyCells(scrollTop);
});

// Dismiss tooltip/popover on scroll
grid.on('tbw-scroll', () => closeOpenOverlays());

See also: TbwScrollDetail

---

sort-change

grid.on('sort-change', ({ field, direction }) => {
  if (direction === 0) {
    console.log('Sort cleared');
  } else {
    console.log(`Sorted by ${field} ${direction === 1 ? 'ASC' : 'DESC'}`);
  }

  // Server-side sorting
  fetchData({ sortBy: field, sortDir: direction });
});

See also: SortChangeDetail · SortHandler

---

column-resize

grid.on('column-resize', ({ field, width }) => {
  console.log(`Column "${field}" resized to ${width}px`);

  // Persist to localStorage
  const widths = JSON.parse(localStorage.getItem('col-widths') ?? '{}');
  widths[field] = width;
  localStorage.setItem('col-widths', JSON.stringify(widths));
});

See also: ColumnResizeDetail

---

column-resize-reset

grid.on('column-resize-reset', ({ field, width }) => {
  const widths = JSON.parse(localStorage.getItem('col-widths') ?? '{}');
  delete widths[field];
  localStorage.setItem('col-widths', JSON.stringify(widths));
});

See also: ColumnResizeResetDetail

---

column-state-change

grid.on('column-state-change', (state) => {
  localStorage.setItem('grid-state', JSON.stringify(state));
  console.log(`${state.columns.length} columns in state`);
});

// Restore on load
const saved = localStorage.getItem('grid-state');
if (saved) grid.applyColumnState(JSON.parse(saved));

See also: GridColumnState · ColumnState

---

render

Fired once at the end of every render cycle, after all plugin afterRender hooks have run and ready() has resolved.

This is the canonical post-render hook for consumers. Use it instead of setTimeout / double-requestAnimationFrame to act on the rendered DOM after a programmatic mutation.

Note: ready() only resolves once (after the first render). The render event fires on every flush — including scroll-driven virtual-window updates — so prefer { once: true } (or check detail.phase) when you want to act on a specific mutation.

// Focus the first cell's input after addRow in full-grid edit mode
grid.addRow({ id: crypto.randomUUID(), name: '', email: '' });
grid.addEventListener(
  'render',
  () => {
    const input = grid.querySelector<HTMLInputElement>(
      '[data-row="0"][data-col="0"] input',
    );
    input?.focus();
  },
  { once: true },
);

See also: RenderDetail

---

Framework Adapter Events

Property	Type	Description
mount-external-view	ExternalMountViewDetail<TRow>	Emitted when a cell with an external view renderer (React, Angular, Vue component) needs to be mounted. Framework adapters listen for this event internally.
mount-external-editor	ExternalMountEditorDetail<TRow>	Emitted when a cell with an external editor component (React, Angular, Vue) needs to be mounted with commit/cancel bindings. Framework adapters listen for this event internally.

Property Details

mount-external-view

// Custom framework adapter
grid.on('mount-external-view', ({ placeholder, spec, context }) => {
  myFramework.render(spec.component, placeholder, {
    row: context.row,
    value: context.value,
  });
});

See also: ExternalMountViewDetail · FrameworkAdapter

---

mount-external-editor

// Custom framework adapter
grid.on('mount-external-editor', ({ placeholder, spec, context }) => {
  myFramework.render(spec.component, placeholder, {
    value: context.value,
    onSave: context.commit,
    onCancel: context.cancel,
  });
});

See also: ExternalMountEditorDetail · FrameworkAdapter

---

Clipboard Events

Property	Type	Description
copy	CopyDetail	Fired after a successful copy operation. Provides the copied text, row count, and column count.
paste	PasteDetail	Fired after a paste operation. Provides parsed rows, target cell, and column fields.

Context Menu Events

Property	Type	Description
context-menu-open	ContextMenuOpenDetail	Fired when the context menu opens. Provides the trigger context and resolved menu items.

Editing Events

Property	Type	Description
cell-cancel	CellCancelDetail	Fired when a cell edit is canceled (Escape key). The cell reverts to its previous value.
cell-commit	CellCommitDetail<TRow>	Fired when a cell value is committed (cancelable).
row-commit	RowCommitDetail<TRow>	Fired when a row editing session ends.
changed-rows-reset	ChangedRowsResetDetail<TRow>	Fired when changed rows tracking is reset.
edit-open	EditOpenDetail<TRow>	Fired when a row enters edit mode (row mode only, not grid mode).
before-edit-close	BeforeEditCloseDetail<TRow>	Fired synchronously before editing state is cleared. Commit callbacks are still active.
edit-close	EditCloseDetail<TRow>	Fired when a row leaves edit mode, whether committed or reverted (row mode only).
dirty-change	DirtyChangeDetail<TRow>	Fired when a row’s dirty state changes (requires dirtyTracking: true).
baselines-captured	BaselinesCapturedDetail	Fired after the render pipeline completes when new baselines were captured (requires dirtyTracking: true).

Export Events

Property	Type	Description
export-complete	ExportCompleteDetail	Fired when an export operation completes. Provides the format, filename, and row/column counts.

Filtering Events

Property	Type	Description
filter-change	FilterChangeDetail	Fired when filter criteria change. Respects silent: true batching — only the final non-silent call emits.

Grouping Events

Property	Type	Description
group-toggle	GroupToggleDetail	Fired when a row group is expanded or collapsed.
group-expand	GroupExpandDetail	Fired when a pre-defined group is expanded.
group-collapse	GroupCollapseDetail	Fired when a pre-defined group is collapsed.

Master-Detail Events

Property	Type	Description
detail-expand	DetailExpandDetail	Fired when a detail panel is expanded or collapsed.

Print Events

Property	Type	Description
print-start	PrintStartDetail	Fired when printing begins. Provides row count and whether a limit was applied.
print-complete	PrintCompleteDetail	Fired when printing completes. Provides success status, row count, and duration.

Column Reorder Events

Property	Type	Description
column-move	ColumnMoveDetail	Fired when a column is reordered via drag-and-drop (cancelable). Call preventDefault() to reject the move.

Responsive Events

Property	Type	Description
responsive-change	ResponsiveChangeDetail	Fired when the grid crosses a responsive breakpoint.

Row Drag-Drop Events

Property	Type	Description
row-move	RowMoveDetail<TRow>	Fired when a row is reordered within a single grid (drag or keyboard). Cancelable — call preventDefault() to revert the move. Cross-grid drops emit row-transfer / row-drop instead.
row-drag-start	RowDragStartDetail<TRow>	Fired on the source grid when a row drag begins. Cancelable — call preventDefault() to abort the drag.
row-drag-end	RowDragEndDetail<TRow>	Fired on the source grid when a row drag ends, regardless of outcome. detail.accepted is true only for cross-grid drops that landed.
row-drop	RowDropDetail<TRow>	Fired on the target grid when a cross-grid drop is about to be applied. Cancelable — call preventDefault() to reject the drop. Not fired for intra-grid moves (those still emit row-move).
row-transfer	RowTransferDetail<TRow>	Fired on both the source and target grid after a successful cross-grid drop. Use this to persist changes in your data store.

Selection Events

Property	Type	Description
selection-change	SelectionChangeDetail	Fired when the selection changes — row click, range drag, Ctrl+click, or programmatic update.

Tree Events

Property	Type	Description
tree-expand	TreeExpandDetail	Fired when a tree node is expanded or collapsed. Provides the node key, row data, and depth level.
tree-load-start	void	Fired when lazy tree data starts loading.
tree-load-end	object	Fired when lazy tree data finishes loading.
tree-load-error	object	Fired when lazy tree data loading fails.

Undo/Redo Events

Property	Type	Description
undo	UndoRedoDetail	Fired after an undo operation (Ctrl+Z). Provides the undone action.
redo	UndoRedoDetail	Fired after a redo operation (Ctrl+Y). Provides the redone action.

Visibility Events

Property	Type	Description
column-reorder-request	ColumnReorderRequestDetail	Fired when the user drag-reorders columns in the visibility sidebar panel. Consumed by ReorderPlugin to perform the actual column move.
column-visibility	ColumnVisibilityDetail	Fired when a column is shown or hidden — either via the visibility sidebar, grid.toggleColumnVisibility(field), grid.setColumnVisible(field, visible), or grid.showAllColumns(). The field and visible properties are present for single-column toggles and undefined for bulk operations (showAllColumns); visibleColumns always lists the current set.

See Also

• DataGridElement.on for the recommended subscription API
• DataGridCustomEvent for typed CustomEvent wrapper