0
# Core Table Functionality
1

2
The core table functionality provides the foundation for all React Table features. Every table implementation starts with the `useTable` hook and its required configuration.
3

4
## Capabilities
5

6
### useTable Hook
7

8
The primary hook that creates and manages the table instance. This is the foundation hook that must be used for all table functionality.
9

10
```javascript { .api }
11
/**
12
 * Creates a table instance with the provided data and columns
13
 * @param props - Table configuration options
14
 * @param plugins - Plugin hooks to extend functionality
15
 * @returns Table instance with state, methods, and computed values
16
 */
17
function useTable(
18
  props: TableOptions,
19
  ...plugins: PluginHook[]
20
): TableInstance;
21

22
interface TableOptions {
23
  /** Array of data objects to display in the table */
24
  data: any[];
25
  /** Array of column definitions */
26
  columns: Column[];
27
  /** Initial table state */
28
  initialState?: Partial<TableState>;
29
  /** Default column configuration that applies to all columns */
30
  defaultColumn?: Partial<Column>;
31
  /** Function to extract sub-rows from a row (for nested data) */
32
  getSubRows?: (row: any, index: number) => any[];
33
  /** Function to generate unique row IDs */
34
  getRowId?: (row: any, index: number, parent?: Row) => string;
35
  /** Custom state reducer for controlling state updates */
36
  stateReducer?: (
37
    newState: TableState,
38
    action: ActionType,
39
    previousState: TableState
40
  ) => TableState;
41
  /** Hook to control the final state after all reducers */
42
  useControlledState?: (state: TableState) => TableState;
43
}
44

45
interface TableInstance {
46
  // State Management
47
  state: TableState;
48
  dispatch: (action: ActionType) => void;
49
  
50
  // Column Information
51
  columns: Column[];
52
  allColumns: Column[];
53
  visibleColumns: Column[];
54
  headerGroups: HeaderGroup[];
55
  footerGroups: HeaderGroup[];
56
  headers: Header[];
57
  flatHeaders: Header[];
58
  
59
  // Row Information  
60
  rows: Row[];
61
  flatRows: Row[];
62
  rowsById: Record<string, Row>;
63
  
64
  // Core Methods
65
  prepareRow: (row: Row) => void;
66
  getTableProps: PropGetter;
67
  getTableBodyProps: PropGetter;
68
}
69
```
70

71
**Usage Example:**
72

73
```javascript
74
import React from 'react';
75
import { useTable } from 'react-table';
76

77
function BasicTable() {
78
  const data = React.useMemo(() => [
79
    { id: 1, name: 'John', age: 30 },
80
    { id: 2, name: 'Jane', age: 25 },
81
  ], []);
82

83
  const columns = React.useMemo(() => [
84
    {
85
      Header: 'Name',
86
      accessor: 'name',
87
    },
88
    {
89
      Header: 'Age',
90
      accessor: 'age',
91
    },
92
  ], []);
93

94
  const tableInstance = useTable({
95
    columns,
96
    data,
97
  });
98

99
  const {
100
    getTableProps,
101
    getTableBodyProps,
102
    headerGroups,
103
    rows,
104
    prepareRow,
105
  } = tableInstance;
106

107
  return (
108
    <table {...getTableProps()}>
109
      <thead>
110
        {headerGroups.map(headerGroup => (
111
          <tr {...headerGroup.getHeaderGroupProps()}>
112
            {headerGroup.headers.map(column => (
113
              <th {...column.getHeaderProps()}>
114
                {column.render('Header')}
115
              </th>
116
            ))}
117
          </tr>
118
        ))}
119
      </thead>
120
      <tbody {...getTableBodyProps()}>
121
        {rows.map(row => {
122
          prepareRow(row);
123
          return (
124
            <tr {...row.getRowProps()}>
125
              {row.cells.map(cell => (
126
                <td {...cell.getCellProps()}>
127
                  {cell.render('Cell')}
128
                </td>
129
              ))}
130
            </tr>
131
          );
132
        })}
133
      </tbody>
134
    </table>
135
  );
136
}
137
```
138

139
### Column Configuration
140

141
Columns define how data is accessed, displayed, and behave in the table.
142

143
```javascript { .api }
144
interface Column {
145
  /** Column header content (component, string, or render function) */
146
  Header?: Renderer;
147
  /** Column footer content */
148
  Footer?: Renderer;
149
  /** Cell renderer (defaults to displaying the value) */
150
  Cell?: Renderer;
151
  /** Data accessor - string key or function to extract cell value */
152
  accessor?: string | ((row: any, index: number) => any);
153
  /** Unique column identifier (auto-generated if not provided) */
154
  id?: string;
155
  /** Column width in pixels */
156
  width?: number;
157
  /** Minimum column width */
158
  minWidth?: number;
159
  /** Maximum column width */
160
  maxWidth?: number;
161
  /** Whether this column can be sorted */
162
  disableSortBy?: boolean;
163
  /** Whether this column can be filtered */
164
  disableFilters?: boolean;
165
  /** Whether this column can be grouped */
166
  disableGroupBy?: boolean;
167
  /** Whether this column is visible */
168
  show?: boolean;
169
}
170

171
interface HeaderGroup {
172
  headers: Header[];
173
  getHeaderGroupProps: PropGetter;
174
}
175

176
interface Header {
177
  id: string;
178
  column: Column;
179
  Header: Renderer;
180
  getHeaderProps: PropGetter;
181
  render: (type: string) => React.ReactElement;
182
}
183
```
184

185
**Column Definition Examples:**
186

187
```javascript
188
const columns = [
189
  // Simple string accessor
190
  {
191
    Header: 'First Name',
192
    accessor: 'firstName',
193
  },
194
  
195
  // Function accessor for computed values
196
  {
197
    Header: 'Full Name',
198
    id: 'fullName',
199
    accessor: row => `${row.firstName} ${row.lastName}`,
200
  },
201
  
202
  // Custom cell renderer
203
  {
204
    Header: 'Status',
205
    accessor: 'status',
206
    Cell: ({ value }) => (
207
      <span className={`status-${value}`}>
208
        {value}
209
      </span>
210
    ),
211
  },
212
  
213
  // Column with width constraints
214
  {
215
    Header: 'Actions',
216
    id: 'actions',
217
    width: 100,
218
    minWidth: 100,
219
    maxWidth: 100,
220
    Cell: ({ row }) => (
221
      <button onClick={() => handleEdit(row.original)}>
222
        Edit
223
      </button>
224
    ),
225
  },
226
];
227
```
228

229
### Row and Cell Objects
230

231
Rows and cells provide structured access to data and rendering utilities.
232

233
```javascript { .api }
234
interface Row {
235
  /** Unique row identifier */
236
  id: string;
237
  /** Row index in the data array */  
238
  index: number;
239
  /** Original data object for this row */
240
  original: any;
241
  /** Array of cell objects for this row */
242
  cells: Cell[];
243
  /** Object containing all computed column values */
244
  values: Record<string, any>;
245
  /** Sub-rows (for hierarchical data) */
246
  subRows?: Row[];
247
  /** Get props for the row element */
248
  getRowProps: PropGetter;
249
}
250

251
interface Cell {
252
  /** Column definition for this cell */
253
  column: Column;
254
  /** Row containing this cell */
255
  row: Row;
256
  /** Computed value for this cell */
257
  value: any;
258
  /** Get props for the cell element */
259
  getCellProps: PropGetter;
260
  /** Render the cell content */
261
  render: (type: string) => React.ReactElement;
262
}
263
```
264

265
### Prop Getters
266

267
Prop getters provide HTML attributes and event handlers for table elements.
268

269
```javascript { .api }
270
type PropGetter = (props?: any) => object;
271

272
interface PropGetterMethods {
273
  /** Get props for the table element */
274
  getTableProps: PropGetter;
275
  /** Get props for the table body element */
276
  getTableBodyProps: PropGetter;
277
  /** Get props for header group rows */
278
  getHeaderGroupProps: PropGetter;
279
  /** Get props for individual headers */
280
  getHeaderProps: PropGetter;
281
  /** Get props for table rows */
282
  getRowProps: PropGetter;
283
  /** Get props for table cells */
284
  getCellProps: PropGetter;
285
}
286
```
287

288
**Prop Getter Usage:**
289

290
```javascript
291
// Basic usage
292
<table {...getTableProps()}>
293
  <tbody {...getTableBodyProps()}>
294
    {rows.map(row => (
295
      <tr {...row.getRowProps()}>
296
        {row.cells.map(cell => (
297
          <td {...cell.getCellProps()}>
298
            {cell.render('Cell')}
299
          </td>
300
        ))}
301
      </tr>
302
    ))}
303
  </tbody>
304
</table>
305

306
// Adding custom props
307
<table {...getTableProps({ className: 'my-table' })}>
308
  <tr {...row.getRowProps({
309
    onClick: () => handleRowClick(row),
310
    className: row.isSelected ? 'selected' : ''
311
  })}>
312
    {/* cells */}
313
  </tr>
314
</table>
315
```
316

317
### State Management
318

319
React Table manages internal state but allows for external control and customization.
320

321
```javascript { .api }
322
interface TableState {
323
  /** Current page index (with usePagination) */
324
  pageIndex?: number;
325
  /** Current page size (with usePagination) */
326
  pageSize?: number;
327
  /** Current sort configuration (with useSortBy) */
328
  sortBy?: SortingRule[];
329
  /** Column filter values (with useFilters) */
330
  filters?: Filter[];
331
  /** Global filter value (with useGlobalFilter) */
332
  globalFilter?: any;
333
  /** Column visibility (with useColumnVisibility) */
334
  hiddenColumns?: string[];
335
  /** Selected row IDs (with useRowSelect) */
336
  selectedRowIds?: Record<string, boolean>;
337
  /** Expanded row IDs (with useExpanded) */
338
  expanded?: Record<string, boolean>;
339
  /** Column order (with useColumnOrder) */
340
  columnOrder?: string[];
341
  /** Row state by row ID (with useRowState) */
342
  rowState?: Record<string, any>;
343
}
344

345
interface ActionType {
346
  type: string;
347
  [key: string]: any;
348
}
349
```
350

351
**State Control Example:**
352

353
```javascript
354
// Controlled state
355
const [tableState, setTableState] = React.useState({
356
  pageIndex: 0,
357
  pageSize: 10,
358
});
359

360
const tableInstance = useTable(
361
  {
362
    columns,
363
    data,
364
    initialState: tableState,
365
    // Control state updates
366
    stateReducer: (newState, action) => {
367
      setTableState(newState);
368
      return newState;
369
    },
370
  },
371
  usePagination
372
);
373
```
374

375
### Required Preparation
376

377
Before rendering rows, you must call `prepareRow` for each row to ensure proper initialization.
378

379
```javascript { .api }
380
/**
381
 * Prepares a row for rendering by initializing its cells and properties
382
 * @param row - The row to prepare
383
 */
384
prepareRow: (row: Row) => void;
385
```
386

387
**Critical Usage Pattern:**
388

389
```javascript
390
// REQUIRED: Call prepareRow before rendering
391
{rows.map(row => {
392
  prepareRow(row); // This must be called!
393
  return (
394
    <tr {...row.getRowProps()}>
395
      {row.cells.map(cell => (
396
        <td {...cell.getCellProps()}>
397
          {cell.render('Cell')}
398
        </td>
399
      ))}
400
    </tr>
401
  );
402
})}
403
```
404

405
## Types
406

407
```javascript { .api }
408
type Renderer = 
409
  | React.ComponentType<any>
410
  | React.ReactElement
411
  | string
412
  | ((props: any) => React.ReactElement);
413

414
interface PluginHook {
415
  (hooks: Hooks): void;
416
  pluginName?: string;
417
}
418

419
interface Hooks {
420
  columns: Array<(columns: Column[], meta: any) => Column[]>;
421
  allColumns: Array<(columns: Column[], meta: any) => Column[]>;
422
  visibleColumns: Array<(columns: Column[], meta: any) => Column[]>;
423
  headerGroups: Array<(headerGroups: HeaderGroup[], meta: any) => HeaderGroup[]>;
424
  useOptions: Array<(options: any, meta: any) => any>;
425
  stateReducers: Array<(state: any, action: any, prevState: any, instance: any) => any>;
426
  useControlledState: Array<(state: any, meta: any) => any>;
427
  useInstanceAfterData: Array<(instance: any) => void>;
428
}
429
```