0
# Material-UI Data Grid
1

2
Material-UI Data Grid is the community edition of the data grid component for React applications using Material-UI design system. It provides essential data grid functionality including sorting, filtering, pagination, and cell editing capabilities while maintaining compatibility with Material-UI's theming system.
3

4
## Package Information
5

6
- **Package Name**: @material-ui/data-grid
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @material-ui/data-grid`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  DataGrid, 
16
  useApiRef, 
17
  classnames 
18
} from "@material-ui/data-grid";
19
```
20

21
Additional commonly used imports:
22

23
```typescript
24
import { 
25
  DataGrid,
26
  useApiRef,
27
  classnames,
28
  type DataGridProps,
29
  type ColDef,
30
  type RowData,
31
  type GridApi,
32
  type ApiRef,
33
  type CellParams,
34
  type RowParams
35
} from "@material-ui/data-grid";
36
```
37

38
For CommonJS:
39

40
```javascript
41
const { 
42
  DataGrid, 
43
  useApiRef, 
44
  classnames 
45
} = require("@material-ui/data-grid");
46
```
47

48
## Basic Usage
49

50
```typescript
51
import React from "react";
52
import { DataGrid } from "@material-ui/data-grid";
53

54
const columns = [
55
  { field: "id", headerName: "ID", width: 90 },
56
  { field: "firstName", headerName: "First name", width: 150 },
57
  { field: "lastName", headerName: "Last name", width: 150 },
58
  { field: "age", headerName: "Age", type: "number", width: 110 },
59
];
60

61
const rows = [
62
  { id: 1, lastName: "Snow", firstName: "Jon", age: 35 },
63
  { id: 2, lastName: "Lannister", firstName: "Cersei", age: 42 },
64
  { id: 3, lastName: "Lannister", firstName: "Jaime", age: 45 },
65
];
66

67
function MyDataGrid() {
68
  return (
69
    <div style={{ height: 400, width: "100%" }}>
70
      <DataGrid
71
        rows={rows}
72
        columns={columns}
73
        pageSize={5}
74
        rowsPerPageOptions={[5]}
75
        checkboxSelection
76
      />
77
    </div>
78
  );
79
}
80
```
81

82
## Architecture
83

84
The Material-UI Data Grid is built around several key components:
85

86
- **DataGrid Component**: Main React component with restricted community features
87
- **Column System**: Flexible column definitions with built-in column types (string, number, date)
88
- **Row Management**: Efficient row handling with selection and state management
89
- **Virtualization**: Performance optimization for large datasets through virtual scrolling
90
- **Event System**: Comprehensive event handling for user interactions
91
- **API Reference**: Imperative API for programmatic grid control
92

93
Community edition limitations:
94
- Maximum page size: 100 rows
95
- Single column sorting only
96
- Single row selection only
97
- Pagination is always enabled
98

99
## Capabilities
100

101
### DataGrid Component
102

103
Core React component for rendering data grids with Material-UI styling and theming integration.
104

105
```typescript { .api }
106
declare const DataGrid: React.ForwardRefExoticComponent<
107
  DataGridProps & React.RefAttributes<HTMLDivElement>
108
>;
109

110
interface DataGridProps extends DataGridOptionsProp {
111
  /** Array of row data objects */
112
  rows: RowsProp;
113
  /** Array of column definition objects */
114
  columns: Columns;
115
  /** Custom component overrides */
116
  components?: GridComponentOverridesProp;
117
  /** Loading state indicator */
118
  loading?: boolean;
119
  /** CSS class name */
120
  className?: string;
121
  /** Error state to display */
122
  error?: any;
123
}
124

125
type RowsProp = RowData[];
126
type Columns = ColDef[];
127
```
128

129
[DataGrid Component](./data-grid-component.md)
130

131
### Column Definitions
132

133
Column configuration system supporting various data types, custom renderers, and display options.
134

135
```typescript { .api }
136
interface ColDef {
137
  /** Column identifier for mapping to row data */
138
  field: string;
139
  /** Display name in column header */
140
  headerName?: string;
141
  /** Column width in pixels */
142
  width?: number;
143
  /** Column data type */
144
  type?: ColType;
145
  /** Cell value alignment */
146
  align?: Alignment;
147
  /** Sort comparator function */
148
  sortComparator?: ComparatorFn;
149
  /** Custom cell renderer */
150
  renderCell?: (params: CellParams) => React.ReactElement;
151
  /** Custom header renderer */
152
  renderHeader?: (params: ColParams) => React.ReactElement;
153
  /** Value getter function */
154
  valueGetter?: (params: ValueGetterParams) => CellValue;
155
  /** Value formatter function */
156
  valueFormatter?: (params: ValueFormatterParams) => CellValue;
157
}
158

159
type ColType = "string" | "number" | "date" | "dateTime" | "boolean";
160
type Alignment = "left" | "right" | "center";
161
```
162

163
[Column System](./column-system.md)
164

165
### Row Data and Management
166

167
Row data structure and management capabilities including selection and state handling.
168

169
```typescript { .api }
170
interface RowData extends ObjectWithId {
171
  id: RowId;
172
  [key: string]: any;
173
}
174

175
interface RowModel {
176
  id: RowId;
177
  data: RowData;
178
  selected: boolean;
179
}
180

181
type RowId = string | number;
182
type CellValue = string | number | boolean | Date | null | undefined | object;
183

184
interface ObjectWithId {
185
  id: RowId;
186
}
187
```
188

189
[Row Management](./row-management.md)
190

191
### Grid Options and Configuration
192

193
Comprehensive configuration options for customizing grid behavior, appearance, and functionality.
194

195
```typescript { .api }
196
interface DataGridOptionsProp extends Partial<GridOptions> {
197
  // Community edition excludes pagination, disableMultipleColumnsSorting, disableMultipleSelection
198
}
199

200
interface GridOptions {
201
  /** Dynamic height based on content */
202
  autoHeight?: boolean;
203
  /** Row height in pixels */
204
  rowHeight: number;
205
  /** Header height in pixels */
206
  headerHeight: number;
207
  /** Scrollbar size in pixels */
208
  scrollbarSize: number;
209
  /** Number of columns rendered outside viewport */
210
  columnBuffer: number;
211
  /** Page size for pagination */
212
  pageSize?: number;
213
  /** Available page size options */
214
  rowsPerPageOptions?: number[];
215
  /** Enable checkbox selection */
216
  checkboxSelection?: boolean;
217
  /** Hide footer components */
218
  hideFooter?: boolean;
219
  hideFooterRowCount?: boolean;
220
  hideFooterPagination?: boolean;
221
}
222
```
223

224
[Configuration Options](./configuration-options.md)
225

226
### Event Handling
227

228
Event system for handling user interactions with cells, rows, columns, and pagination.
229

230
```typescript { .api }
231
interface GridOptions {
232
  /** Cell click handler */
233
  onCellClick?: (param: CellParams) => void;
234
  /** Cell hover handler */
235
  onCellHover?: (param: CellParams) => void;
236
  /** Row click handler */
237
  onRowClick?: (param: RowParams) => void;
238
  /** Row selection handler */
239
  onRowSelected?: (param: RowSelectedParams) => void;
240
  /** Selection change handler */
241
  onSelectionChange?: (param: SelectionChangeParams) => void;
242
  /** Column header click handler */
243
  onColumnHeaderClick?: (param: ColParams) => void;
244
  /** Sort model change handler */
245
  onSortModelChange?: (params: SortModelParams) => void;
246
  /** Page change handler */
247
  onPageChange?: (param: PageChangeParams) => void;
248
  /** Error handler */
249
  onError?: (args: any) => void;
250
}
251
```
252

253
[Event Handling](./event-handling.md)
254

255
### API Reference and Hooks
256

257
Imperative API and React hooks for programmatic grid control and state management.
258

259
```typescript { .api }
260
/** Hook to create API reference */
261
function useApiRef(): ApiRef;
262

263
type ApiRef = React.MutableRefObject<GridApi>;
264

265
interface GridApi extends CoreApi, EventsApi, RowApi, ColumnApi, 
266
  SelectionApi, SortApi, VirtualizationApi, PaginationApi {
267
  // Combined API interface
268
}
269
```
270

271
[API Reference](./api-reference.md)
272

273
### Utilities
274

275
Helper functions and utilities for common grid operations, styling, keyboard handling, and DOM manipulation.
276

277
```typescript { .api }
278
/** Utility function for combining CSS class names */
279
function classnames(...args: any[]): string;
280

281
// Keyboard Utilities
282
/** Array of keys that enable multiple selection */
283
const MULTIPLE_SELECTION_KEYS: string[];
284
/** Check if key code enables multiple selection */
285
function isMultipleKey(code: string): boolean;
286
/** Check if key is Tab */
287
function isTabKey(code: string): boolean;
288
/** Check if key is Space */
289
function isSpaceKey(code: string): boolean;
290
/** Check if key is an arrow key */
291
function isArrowKeys(code: string): boolean;
292
/** Check if key is Home or End */
293
function isHomeOrEndKeys(code: string): boolean;
294
/** Check if key is Page Up or Page Down */
295
function isPageKeys(code: string): boolean;
296
/** Check if key is a navigation key */
297
function isNavigationKey(code: string): boolean;
298

299
// DOM Utilities
300
/** Check if element has overflow */
301
function isOverflown(element: Element): boolean;
302
/** Find parent element by class name */
303
function findParentElementFromClassName(elem: Element, className: string): Element | null;
304
/** Check if element is a grid cell */
305
function isCell(elem: Element | null): boolean;
306
/** Check if element is a header cell */
307
function isHeaderCell(elem: Element): boolean;
308
/** Get row ID from row element */
309
function getIdFromRowElem(rowEl: Element): string;
310
/** Find grid root element from current element */
311
function findGridRootFromCurrent(elem: Element): HTMLDivElement | null;
312

313
// Type Checking Utilities
314
/** Check if value is a Date */
315
function isDate(value: any): value is Date;
316
/** Check if value is an array */
317
function isArray(value: any): value is Array<any>;
318
/** Check if value is a string */
319
function isString(value: any): value is string;
320
/** Check if value is a number */
321
function isNumber(value: any): value is number;
322
/** Check if value is a function */
323
function isFunction(value: any): value is Function;
324
/** Check if value is an object */
325
function isObject(value: any): value is Record<string, any>;
326

327
// Sorting Utilities
328
/** Get next sort direction in cycle */
329
function nextSortDirection(sortingOrder: SortDirection[], current?: SortDirection): SortDirection;
330
/** Check if sort direction is descending */
331
function isDesc(direction: SortDirection): boolean;
332
/** Comparator for string/number values */
333
const stringNumberComparer: ComparatorFn;
334
/** Comparator for numeric values */
335
const numberComparer: ComparatorFn;
336
/** Comparator for date values */
337
const dateComparer: ComparatorFn;
338
```
339

340
## Types
341

342
### Core Data Types
343

344
```typescript { .api }
345
interface CellParams {
346
  /** The HTMLElement that triggered the event */
347
  element?: HTMLElement;
348
  /** The column field of the cell that triggered the event */
349
  field: string;
350
  /** The cell value */
351
  value: CellValue;
352
  /** A function that lets you get data from other columns */
353
  getValue: (field: string) => CellValue;
354
  /** The full set of data of the row that the current cell belongs to */
355
  data: RowData;
356
  /** The row model of the row that the current cell belongs to */
357
  rowModel: RowModel;
358
  /** The column of the row that the current cell belongs to */
359
  colDef: any;
360
  /** The row index of the row that the current cell belongs to */
361
  rowIndex: number;
362
  /** ApiRef that lets you manipulate the grid */
363
  api: any;
364
}
365

366
interface RowParams {
367
  id: RowId;
368
  columns: Columns;
369
  row: RowData;
370
  api: GridApi;
371
}
372

373
interface ColParams {
374
  field: string;
375
  colDef: ColDef;
376
  api: GridApi;
377
}
378

379
interface SortModel {
380
  field: string;
381
  sort: SortDirection;
382
}
383

384
type SortDirection = "asc" | "desc" | null;
385
type ComparatorFn = (v1: CellValue, v2: CellValue) => number;
386
```
387

388
### Component Override Types
389

390
```typescript { .api }
391
interface GridComponentOverridesProp {
392
  /** Custom footer component */
393
  Footer?: React.ComponentType<any>;
394
  /** Custom header component */
395
  Header?: React.ComponentType<any>;
396
  /** Custom toolbar component */
397
  Toolbar?: React.ComponentType<any>;
398
  /** Custom loading overlay */
399
  LoadingOverlay?: React.ComponentType;
400
  /** Custom no rows overlay */
401
  NoRowsOverlay?: React.ComponentType;
402
  /** Custom pagination component */
403
  Pagination?: React.ComponentType<any>;
404
  /** Custom column header component */
405
  ColumnHeader?: React.ComponentType<any>;
406
  /** Custom cell component */
407
  Cell?: React.ComponentType<CellParams>;
408
  /** Custom row component */
409
  Row?: React.ComponentType<any>;
410
}
411
```