0
# Core Grid API
1

2
The ReactDataGrid component is the primary interface for creating Excel-like data grids with virtual rendering, editing capabilities, and comprehensive user interaction support.
3

4
## Capabilities
5

6
### ReactDataGrid Component
7

8
Main grid component that renders tabular data with virtual scrolling, editing, sorting, and filtering capabilities.
9

10
```javascript { .api }
11
/**
12
 * Main data grid component with Excel-like functionality
13
 * @param props - Configuration object for the grid
14
 * @returns JSX.Element representing the data grid
15
 */
16
function ReactDataGrid(props: ReactDataGridProps): JSX.Element;
17

18
interface ReactDataGridProps {
19
  // Required Configuration
20
  /** Array of column definitions */
21
  columns: Column[];
22
  /** Function to retrieve row data by index */
23
  rowGetter: (index: number) => any;
24
  /** Total number of rows to display */
25
  rowsCount: number;
26
  /** Minimum height of the grid in pixels */
27
  minHeight: number;
28
  
29
  // Layout Configuration
30
  /** Height of each data row in pixels (default: 35) */
31
  rowHeight?: number;
32
  /** Height of the header row in pixels */
33
  headerRowHeight?: number;
34
  /** Height of the filter row in pixels (default: 45) */
35
  headerFiltersHeight?: number;
36
  /** Minimum width of the grid in pixels */
37
  minWidth?: number;
38
  /** Minimum column width in pixels (default: 80) */
39
  minColumnWidth?: number;
40
  
41
  // Interaction Configuration
42
  /** Enable cell selection functionality (default: false) */
43
  enableCellSelect?: boolean;
44
  /** Cell navigation behavior mode (default: 'none') */
45
  cellNavigationMode?: 'none' | 'loopOverRow' | 'changeRow';
46
  /** Enable drag and drop functionality */
47
  enableDragAndDrop?: boolean;
48
  /** Enable automatic cell focus (default: true) */
49
  enableCellAutoFocus?: boolean;
50
  
51
  // Row Configuration
52
  /** Primary key property name for rows (default: 'id') */
53
  rowKey?: string;
54
  /** Row index to scroll to on render (default: 0) */
55
  scrollToRowIndex?: number;
56
  
57
  // Event Handlers - Data Updates
58
  /** Called when grid data is updated via editing, copy/paste, or drag */
59
  onGridRowsUpdated?: (event: GridRowsUpdatedEvent) => void;
60
  /** Called before a cell becomes editable */
61
  onCheckCellIsEditable?: (event: CheckCellEditableEvent) => boolean;
62
  /** Called just before a cell editing begins */
63
  onBeforeEdit?: (event: BeforeEditEvent) => void;
64
  
65
  // Event Handlers - Selection
66
  /** Called when a row is selected */
67
  onRowSelect?: (rowIdx: number, row: any) => void;
68
  /** Called when a cell is selected */
69
  onCellSelected?: (position: Position) => void;
70
  /** Called when a cell is deselected */
71
  onCellDeSelected?: (position: Position) => void;
72
  /** Called when a cell is expanded */
73
  onCellExpand?: (args: CellExpandArgs) => void;
74
  
75
  // Event Handlers - User Interaction
76
  /** Called when a row is clicked */
77
  onRowClick?: (rowIdx: number, row: any, column: Column) => void;
78
  /** Called when a row is double-clicked */
79
  onRowDoubleClick?: (rowIdx: number, row: any, column: Column) => void;
80
  /** Called on keyboard key down events */
81
  onGridKeyDown?: (event: GridKeyboardEvent) => void;
82
  /** Called on keyboard key up events */
83
  onGridKeyUp?: (event: GridKeyboardEvent) => void;
84
  
85
  // Event Handlers - Sorting and Filtering
86
  /** Called when grid is sorted */
87
  onGridSort?: (sortColumn: string, sortDirection: SortDirection) => void;
88
  /** Called when grid is filtered via FilterableHeaderCell */
89
  onFilter?: (filter: Filter) => void;
90
  /** Called when all filters are cleared */
91
  onClearFilters?: () => void;
92
  /** Called when a filter is added */
93
  onAddFilter?: (filter: Filter) => void;
94
  
95
  // Event Handlers - Layout
96
  /** Called when a column is resized */
97
  onColumnResize?: (idx: number, width: number) => void;
98
  /** Called when the grid is scrolled */
99
  onScroll?: (scrollState: ScrollState) => void;
100
  
101
  // Sorting Configuration
102
  /** Key of the currently sorted column */
103
  sortColumn?: string;
104
  /** Direction of the current sort */
105
  sortDirection?: SortDirection;
106
  
107
  // Selection Configuration
108
  /** Row selection configuration */
109
  rowSelection?: RowSelection;
110
  /** Cell range selection configuration */
111
  cellRangeSelection?: CellRangeSelection;
112
  
113
  // Custom Components
114
  /** Toolbar component to display above the grid */
115
  toolbar?: React.ReactElement;
116
  /** Context menu component */
117
  contextMenu?: React.ReactElement;
118
  /** Custom draggable header cell component */
119
  draggableHeaderCell?: React.ComponentType<any>;
120
  /** Custom row group renderer */
121
  rowGroupRenderer?: React.ComponentType<any>;
122
  /** Custom row actions cell renderer */
123
  rowActionsCell?: React.ComponentType<any>;
124
  /** Custom select all renderer */
125
  selectAllRenderer?: React.ComponentType<any>;
126
  
127
  // Advanced Configuration
128
  /** Function to get cell actions for rendering action buttons */
129
  getCellActions?: (column: Column, row: any) => CellAction[];
130
  /** Function to get valid filter values */
131
  getValidFilterValues?: (column: Column) => any[];
132
  /** DOM element where editor portals should mount (default: document.body) */
133
  editorPortalTarget?: Element;
134
  /** Called when row expand/collapse is toggled */
135
  onRowExpandToggle?: (args: RowExpandToggleArgs) => void;
136
  /** Called when a sub-row is deleted */
137
  onDeleteSubRow?: (args: DeleteSubRowArgs) => void;
138
  /** Called when a sub-row is added */
139
  onAddSubRow?: (args: AddSubRowArgs) => void;
140
}
141
```
142

143
### Column Definition
144

145
Configuration object that defines how each column behaves and appears in the grid.
146

147
```javascript { .api }
148
interface Column {
149
  /** Unique identifier for the column */
150
  key: string;
151
  /** Display name shown in the header */
152
  name: string;
153
  
154
  // Layout Properties
155
  /** Column width in pixels */
156
  width?: number;
157
  /** Whether the column can be resized */
158
  resizable?: boolean;
159
  /** Whether the column is frozen (non-scrollable) */
160
  frozen?: boolean;
161
  
162
  // Interaction Properties
163
  /** Whether the column can be sorted */
164
  sortable?: boolean;
165
  /** Sort descending first instead of ascending */
166
  sortDescendingFirst?: boolean;
167
  /** Whether the column can be filtered */
168
  filterable?: boolean;
169
  /** Whether the column can be dragged to reorder */
170
  draggable?: boolean;
171
  
172
  // Editing Properties
173
  /** Whether cells in this column are editable */
174
  editable?: boolean;
175
  /** Custom editor component for this column */
176
  editor?: React.ComponentType<EditorProps>;
177
  
178
  // Display Properties
179
  /** Custom formatter component for cell display */
180
  formatter?: React.ComponentType<FormatterProps>;
181
  /** Custom header renderer component */
182
  headerRenderer?: React.ComponentType<HeaderRendererProps>;
183
  /** Custom filter renderer component */
184
  filterRenderer?: React.ComponentType<FilterRendererProps>;
185
  
186
  // Event Configuration
187
  /** Event handlers specific to this column */
188
  events?: {
189
    [eventName: string]: (event: any, args: any) => void;
190
  };
191
}
192
```
193

194
### Event Types
195

196
Type definitions for grid events and callbacks.
197

198
```javascript { .api }
199
interface GridRowsUpdatedEvent {
200
  fromRow: number;
201
  toRow: number;
202
  updated: { [key: string]: any };
203
  action: 'CELL_UPDATE' | 'COLUMN_FILL' | 'COPY_PASTE' | 'CELL_DRAG';
204
}
205

206
interface Position {
207
  idx: number;
208
  rowIdx: number;
209
}
210

211
interface CheckCellEditableEvent {
212
  row: any;
213
  column: Column;
214
  rowIdx: number;
215
}
216

217
interface BeforeEditEvent {
218
  rowIdx: number;
219
  column: Column;
220
  row: any;
221
}
222

223
interface CellExpandArgs {
224
  rowIdx: number;
225
  idx: number;
226
  rowData: any;
227
  expandArgs: any;
228
}
229

230
interface GridKeyboardEvent {
231
  rowIdx: number;
232
  idx: number;
233
  key: string;
234
}
235

236
type SortDirection = 'ASC' | 'DESC' | 'NONE';
237

238
interface Filter {
239
  columnKey: string;
240
  filterTerm: string;
241
}
242

243
interface ScrollState {
244
  scrollTop: number;
245
  scrollLeft: number;
246
}
247
```
248

249
**Usage Examples:**
250

251
```javascript
252
import ReactDataGrid from 'react-data-grid';
253

254
// Basic configuration with required props
255
const BasicGrid = () => {
256
  const columns = [
257
    { key: 'id', name: 'ID', width: 80 },
258
    { key: 'name', name: 'Name', width: 200 },
259
    { key: 'email', name: 'Email', width: 250 }
260
  ];
261
  
262
  const rows = [
263
    { id: 1, name: 'John Doe', email: 'john@example.com' },
264
    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
265
  ];
266
  
267
  return (
268
    <ReactDataGrid
269
      columns={columns}
270
      rowGetter={i => rows[i]}
271
      rowsCount={rows.length}
272
      minHeight={400}
273
    />
274
  );
275
};
276

277
// Grid with editing and event handling
278
const EditableGrid = () => {
279
  const [rows, setRows] = useState(initialRows);
280
  
281
  const handleGridRowsUpdated = ({ fromRow, toRow, updated }) => {
282
    const newRows = rows.slice();
283
    for (let i = fromRow; i <= toRow; i++) {
284
      newRows[i] = { ...newRows[i], ...updated };
285
    }
286
    setRows(newRows);
287
  };
288
  
289
  const editableColumns = [
290
    { key: 'id', name: 'ID' },
291
    { key: 'name', name: 'Name', editable: true },
292
    { key: 'active', name: 'Active', editable: true }
293
  ];
294
  
295
  return (
296
    <ReactDataGrid
297
      columns={editableColumns}
298
      rowGetter={i => rows[i]}
299
      rowsCount={rows.length}
300
      minHeight={500}
301
      enableCellSelect={true}
302
      onGridRowsUpdated={handleGridRowsUpdated}
303
      onRowClick={(rowIdx, row) => console.log('Row clicked:', row)}
304
    />
305
  );
306
};
307

308
// Grid with sorting and filtering
309
const AdvancedGrid = () => {
310
  const [sortColumn, setSortColumn] = useState('');
311
  const [sortDirection, setSortDirection] = useState('NONE');
312
  
313
  const handleGridSort = (columnKey, direction) => {
314
    setSortColumn(columnKey);
315
    setSortDirection(direction);
316
    // Implement sorting logic
317
  };
318
  
319
  const sortableColumns = [
320
    { key: 'id', name: 'ID', sortable: true },
321
    { key: 'name', name: 'Name', sortable: true, filterable: true },
322
    { key: 'date', name: 'Date', sortable: true }
323
  ];
324
  
325
  return (
326
    <ReactDataGrid
327
      columns={sortableColumns}
328
      rowGetter={i => sortedRows[i]}
329
      rowsCount={sortedRows.length}
330
      minHeight={600}
331
      sortColumn={sortColumn}
332
      sortDirection={sortDirection}
333
      onGridSort={handleGridSort}
334
      onFilter={handleFilter}
335
    />
336
  );
337
};
338
```