Grid Events Reference

Grid Events Reference - Active Grid

Overview

The ActiveGrid provides event handlers for user interactions. React to clicks, data changes, cell activation, and more.

<ActiveGrid
  onRowClick={(row) => console.log('Row clicked:', row)}
  onDataCommit={async (payload) => await saveData(payload)}
  onCellActivate={(row, columnId) => console.log('Cell activated')}
  {...}
/>

Row Events

onRowClick

Type: (row: TData) => void
Description: Triggered when a row is clicked

<ActiveGrid
  onRowClick={(row) => {
    console.log('Clicked user:', row.name);
    router.push(`/users/${row.id}`);
  }}
  {...}
/>

onRowDoubleClick

Type: (row: TData) => void
Description: Triggered when a row is double-clicked

<ActiveGrid
  onRowDoubleClick={(row) => {
    handleEdit(row);
  }}
  {...}
/>

Data Events

onDataCommit

Type: (payload: EditingCommitPayload<TData>) => Promise<void>
Description: Triggered when cell/row editing is committed

interface EditingCommitPayload<TData> {
  rowId: string;
  rowIndex: number;
  oldData: TData;
  newData: TData;
  changes: Partial<TData>;
}

<ActiveGrid
  editMode="cell"
  onDataCommit={async (payload) => {
    console.log('Changes:', payload.changes);
    
    try {
      await api.updateUser(payload.rowId, payload.changes);
      toast.success('Updated successfully');
    } catch (error) {
      toast.error('Update failed');
      throw error; // Revert changes
    }
  }}
  {...}
/>

Payload Properties

rowId - Unique row identifier
rowIndex - Row index in data array
oldData - Original row data
newData - Updated row data
changes - Only the changed fields

Example: Update Single Field

onDataCommit={async (payload) => {
  // payload.changes = { name: 'New Name' }
  await api.updateUser(payload.rowId, payload.changes);
}}

Example: Update Full Row

onDataCommit={async (payload) => {
  await api.updateUser(payload.rowId, payload.newData);
}}

Example: Optimistic Update

function UsersTable() {
  const [users, setUsers] = useState<User[]>([]);
  
  return (
    <ActiveGrid
      data={users}
      onDataCommit={async (payload) => {
        // Optimistically update UI
        setUsers(prev =>
          prev.map(user =>
            user.id === payload.rowId ? payload.newData : user
          )
        );
        
        try {
          await api.updateUser(payload.rowId, payload.changes);
        } catch (error) {
          // Revert on error
          setUsers(prev =>
            prev.map(user =>
              user.id === payload.rowId ? payload.oldData : user
            )
          );
          throw error;
        }
      }}
      {...}
    />
  );
}

Cell Events

onCellActivate

Type: (row: TData, columnId: string) => void
Description: Triggered when a cell is activated via Enter or Space key

Selection Events

onRowSelectionChange

Type: (state: RowSelectionState) => void
Description: Triggered when row selection changes

State Change Events

All table state can be controlled and observed:

onSortingChange

onColumnFiltersChange

onPaginationChange

onColumnVisibilityChange

onColumnSizingChange

Resize Events

columnResizeMode

Type: 'onChange' | 'onEnd'
Default: 'onChange'
Description: When to trigger resize events

Complete Event Example

Event Handler Patterns

With Analytics

With Navigation

With Confirmation

With Validation

With Toast Notifications

Best Practices

✅ DO

Handle errors in onDataCommit
Provide user feedback
Use async/await properly
Validate data before saving
Log important events
Clean up side effects

❌ DON'T

Don't block UI in handlers
Don't skip error handling
Don't mutate state directly
Don't forget to throw on error
Don't ignore event data
Don't create functions in render

Error Handling

Always handle errors in async event handlers:

TypeScript

// Update while dragging
<ActiveGrid
  columnResizeMode="onChange"
  onColumnSizingChange={(sizing) => {
    console.log('Resizing...', sizing);
  }}
  {...}
/>

// Update on drag end only
<ActiveGrid
  columnResizeMode="onEnd"
  onColumnSizingChange={(sizing) => {
    console.log('Resize complete', sizing);
  }}
  {...}
/>

import { useState } from 'react';
import {
  RowSelectionState,
  SortingState,
  ColumnFiltersState,
  PaginationState,
} from '@tanstack/react-table';

function UsersTable() {
  const [users, setUsers] = useState<User[]>([]);
  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
  const [sorting, setSorting] = useState<SortingState>([]);
  const [filters, setFilters] = useState<ColumnFiltersState>([]);
  const [pagination, setPagination] = useState<PaginationState>({
    pageIndex: 0,
    pageSize: 25,
  });
  
  return (
    <ActiveGrid
      columns={columns}
      data={users}
      
      // Row events
      onRowClick={(row) => {
        console.log('Row clicked:', row.id);
      }}
      
      onRowDoubleClick={(row) => {
        router.push(`/users/${row.id}/edit`);
      }}
      
      // Data events
      onDataCommit={async (payload) => {
        try {
          await api.updateUser(payload.rowId, payload.changes);
          toast.success('Updated');
        } catch (error) {
          toast.error('Update failed');
          throw error;
        }
      }}
      
      // Cell events
      onCellActivate={(row, columnId) => {
        console.log('Cell activated:', columnId);
      }}
      
      // State change events
      state={{
        rowSelection,
        sorting,
        columnFilters: filters,
        pagination,
      }}
      
      onRowSelectionChange={setRowSelection}
      
      onSortingChange={(updater) => {
        const newSorting = typeof updater === 'function'
          ? updater(sorting)
          : updater;
        console.log('Sort changed:', newSorting);
        setSorting(newSorting);
      }}
      
      onColumnFiltersChange={(updater) => {
        const newFilters = typeof updater === 'function'
          ? updater(filters)
          : updater;
        console.log('Filters changed:', newFilters);
        setFilters(newFilters);
      }}
      
      onPaginationChange={(updater) => {
        const newPagination = typeof updater === 'function'
          ? updater(pagination)
          : updater;
        console.log('Page changed:', newPagination);
        setPagination(newPagination);
      }}
      
      // Resize mode
      columnResizeMode="onEnd"
    />
  );
}

onDataCommit={async (payload) => {
  // Validate changes
  if (payload.changes.age && payload.changes.age < 18) {
    toast.error('Age must be 18 or older');
    throw new Error('Validation failed');
  }
  
  await api.updateUser(payload.rowId, payload.changes);
}}

onDataCommit={async (payload) => {
  const loadingToast = toast.loading('Saving...');
  
  try {
    await api.updateUser(payload.rowId, payload.changes);
    toast.success('Saved successfully', { id: loadingToast });
  } catch (error) {
    toast.error('Save failed', { id: loadingToast });
    throw error;
  }
}}

onDataCommit={async (payload) => {
  try {
    await api.updateUser(payload.rowId, payload.changes);
  } catch (error) {
    console.error('Update failed:', error);
    toast.error('Update failed');
    throw error; // Important: throw to revert changes
  }
}}

import { EditingCommitPayload } from '@workspace/active-grid';
import { SortingState, RowSelectionState } from '@tanstack/react-table';

type User = {
  id: string;
  name: string;
  email: string;
};

const handleRowClick = (row: User) => {
  console.log(row.name);
};

const handleDataCommit = async (payload: EditingCommitPayload<User>) => {
  await api.updateUser(payload.rowId, payload.changes);
};

const handleSortChange = (sorting: SortingState) => {
  console.log(sorting);
};

<ActiveGrid<User>
  onRowClick={handleRowClick}
  onDataCommit={handleDataCommit}
  onSortingChange={handleSortChange}
  {...}
/>