Skip to content
ToolboxJS

DataGridEventMap

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

Section titled “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

Section titled “Core Events”
PropertyTypeDescription
cell-clickCellClickDetail<TRow>Fired when a cell is clicked. Provides full context: row data, column config, cell element, and the original mouse event.
row-clickRowClickDetail<TRow>Fired when a row is clicked (anywhere on the row). Use for row-level actions like opening a detail panel or navigating.
cell-activateCellActivateDetail<TRow>Fired when a cell is activated by Enter key or pointer click. Unified event for both keyboard and pointer activation — use this instead of the deprecated activate-cell.
cell-changeCellChangeDetail<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-changeDataChangeDetailFired 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.
sort-changeSortChangeDetailFired when the sort state changes — column header click, programmatic sort, or sort cleared. direction: 0 indicates the sort was removed.
column-resizeColumnResizeDetailFired when a column is resized by the user dragging the resize handle. Use to persist column widths to user preferences or localStorage.
activate-cellActivateCellDetail⚠️
column-state-changeGridColumnStateFired when column state changes — reordering, resizing, visibility toggle, or sort changes. Use with getColumnState() / columnState setter for full state persistence.

Property Details

Section titled “Property Details”

cell-click

Section titled “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

Section titled “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

Section titled “cell-activate”

Fired when a cell is activated by Enter key or pointer click. Unified event for both keyboard and pointer activation — use this instead of the deprecated activate-cell.

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

Section titled “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

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

See also: DataChangeDetail

sort-change

Section titled “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

Section titled “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

activate-cell

Section titled “activate-cell”

See also: ActivateCellDetail

column-state-change

Section titled “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.columnState = JSON.parse(saved);

See also: GridColumnState · ColumnState

Framework Adapter Events

Section titled “Framework Adapter Events”
PropertyTypeDescription
mount-external-viewExternalMountViewDetail<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-editorExternalMountEditorDetail<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

Section titled “Property Details”

mount-external-view

Section titled “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

Section titled “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

Section titled “Clipboard Events”
PropertyTypeDescription
copyCopyDetailFired after a successful copy operation. Provides the copied text, row count, and column count.
pastePasteDetailFired after a paste operation. Provides parsed rows, target cell, and column fields.

Context Menu Events

Section titled “Context Menu Events”
PropertyTypeDescription
context-menu-openContextMenuOpenDetailFired when the context menu opens. Provides the trigger context and resolved menu items.

Editing Events

Section titled “Editing Events”
PropertyTypeDescription
cell-cancelCellCancelDetailFired when a cell edit is canceled (Escape key). The cell reverts to its previous value.
cell-commitCellCommitDetail<TRow>Fired when a cell value is committed (cancelable).
row-commitRowCommitDetail<TRow>Fired when a row editing session ends.
changed-rows-resetChangedRowsResetDetail<TRow>Fired when changed rows tracking is reset.
edit-openEditOpenDetail<TRow>Fired when a row enters edit mode (row mode only, not grid mode).
before-edit-closeBeforeEditCloseDetail<TRow>Fired synchronously before editing state is cleared. Commit callbacks are still active.
edit-closeEditCloseDetail<TRow>Fired when a row leaves edit mode, whether committed or reverted (row mode only).
dirty-changeDirtyChangeDetail<TRow>Fired when a row’s dirty state changes (requires dirtyTracking: true).
baselines-capturedBaselinesCapturedDetailFired after the render pipeline completes when new baselines were captured (requires dirtyTracking: true).

Export Events

Section titled “Export Events”
PropertyTypeDescription
export-completeExportCompleteDetailFired when an export operation completes. Provides the format, filename, and row/column counts.

Filtering Events

Section titled “Filtering Events”
PropertyTypeDescription
filter-changeFilterChangeDetailFired when filter criteria change. Respects silent: true batching — only the final non-silent call emits.

Grouping Events

Section titled “Grouping Events”
PropertyTypeDescription
group-toggleGroupToggleDetailFired when a row group is expanded or collapsed.

Master-Detail Events

Section titled “Master-Detail Events”
PropertyTypeDescription
detail-expandDetailExpandDetailFired when a detail panel is expanded or collapsed.
Section titled “Print Events”
PropertyTypeDescription
print-startPrintStartDetailFired when printing begins. Provides row count and whether a limit was applied.
print-completePrintCompleteDetailFired when printing completes. Provides success status, row count, and duration.

Column Reorder Events

Section titled “Column Reorder Events”
PropertyTypeDescription
column-moveColumnMoveDetailFired when a column is reordered via drag-and-drop (cancelable). Call preventDefault() to reject the move.

Row Reorder Events

Section titled “Row Reorder Events”
PropertyTypeDescription
row-moveRowMoveDetail<TRow>Fired when a row is reordered via drag or Shift+arrow (cancelable). Call preventDefault() to reject the move.

Responsive Events

Section titled “Responsive Events”
PropertyTypeDescription
responsive-changeResponsiveChangeDetailFired when the grid crosses a responsive breakpoint.

Selection Events

Section titled “Selection Events”
PropertyTypeDescription
selection-changeSelectionChangeDetailFired when the selection changes — row click, range drag, Ctrl+click, or programmatic update.

Tree Events

Section titled “Tree Events”
PropertyTypeDescription
tree-expandTreeExpandDetailFired when a tree node is expanded or collapsed. Provides the node key, row data, and depth level.

Undo/Redo Events

Section titled “Undo/Redo Events”
PropertyTypeDescription
undoUndoRedoDetailFired after an undo operation (Ctrl+Z). Provides the undone action.
redoUndoRedoDetailFired after a redo operation (Ctrl+Y). Provides the redone action.

See Also

Section titled “See Also”
AI assistants: For complete API documentation, implementation guides, and code examples for this library, see https://raw.githubusercontent.com/OysteinAmundsen/toolbox/main/llms-full.txt