0
# Table Management
1

2
Core table instance creation and lifecycle management functionality. The table instance is the central object that manages all table state and provides access to all table features.
3

4
## Capabilities
5

6
### Table Creation
7

8
Creates a new table instance with the provided options and data.
9

10
```typescript { .api }
11
/**
12
 * Creates a table instance with the provided options
13
 * @param options - Complete table configuration options
14
 * @returns Table instance with all features
15
 */
16
function createTable<TData extends RowData>(
17
  options: TableOptionsResolved<TData>
18
): Table<TData>;
19

20
interface TableOptionsResolved<TData extends RowData> extends 
21
  CoreOptions<TData>,
22
  VisibilityOptions,
23
  ColumnOrderOptions,
24
  ColumnPinningOptions,
25
  RowPinningOptions<TData>,
26
  ColumnFiltersOptions<TData>,
27
  GlobalFilterOptions<TData>,
28
  SortingOptions<TData>,
29
  GroupingOptions,
30
  ExpandedOptions<TData>,
31
  PaginationOptions,
32
  RowSelectionOptions<TData>,
33
  ColumnSizingOptions,
34
  FacetedOptions<TData> {}
35
```
36

37
**Usage Example:**
38

39
```typescript
40
import { createTable, getCoreRowModel } from "@tanstack/table-core";
41

42
const table = createTable({
43
  data: myData,
44
  columns: myColumns,
45
  getCoreRowModel: getCoreRowModel(),
46
  // Feature-specific options
47
  enableSorting: true,
48
  enableFiltering: true,
49
  onStateChange: (updater) => {
50
    // Handle state changes
51
  },
52
});
53
```
54

55
### Core Table Interface
56

57
The main table interface that provides access to all table functionality.
58

59
```typescript { .api }
60
interface Table<TData extends RowData> extends 
61
  CoreInstance<TData>,
62
  HeadersInstance<TData>,
63
  VisibilityInstance<TData>,
64
  ColumnOrderInstance<TData>,
65
  ColumnPinningInstance<TData>,
66
  RowPinningInstance<TData>,
67
  ColumnFiltersInstance<TData>,
68
  GlobalFilterInstance<TData>,
69
  SortingInstance<TData>,
70
  GroupingInstance<TData>,
71
  ExpandedInstance<TData>,
72
  PaginationInstance<TData>,
73
  RowSelectionInstance<TData>,
74
  ColumnSizingInstance,
75
  GlobalFacetingInstance<TData> {}
76
```
77

78
### Core Instance Methods
79

80
Core table methods for accessing columns, rows, and managing state.
81

82
```typescript { .api }
83
interface CoreInstance<TData extends RowData> {
84
  /** Get the initial table state */
85
  initialState: InitialTableState;
86
  /** Reset all table state to initial values */
87
  reset(): void;
88
  /** Get a column by its ID */
89
  getColumn(columnId: string): Column<TData, unknown> | undefined;
90
  /** Get all columns including sub-columns */
91
  getAllColumns(): Column<TData, unknown>[];
92
  /** Get all leaf columns (no sub-columns) */
93
  getAllLeafColumns(): Column<TData, unknown>[];
94
  /** Get all flattened columns */
95
  getAllFlatColumns(): Column<TData, unknown>[];
96
  /** Get the core row model */
97
  getCoreRowModel(): RowModel<TData>;
98
  /** Get the current processed row model */
99
  getRowModel(): RowModel<TData>;
100
  /** Get a row by its ID */
101
  getRow(id: string): Row<TData>;
102
  /** Get the current table state */
103
  getState(): TableState;
104
  /** Set the table state */
105
  setState(updater: Updater<TableState>): void;
106
  /** Set table options */
107
  setOptions(newOptions: Updater<TableOptionsResolved<TData>>): void;
108
}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
// Access table state
115
const currentState = table.getState();
116

117
// Reset table state
118
table.reset();
119

120
// Get specific column
121
const nameColumn = table.getColumn('firstName');
122

123
// Get all columns
124
const allColumns = table.getAllColumns();
125

126
// Access row model
127
const rows = table.getRowModel().rows;
128

129
// Update state
130
table.setState(old => ({
131
  ...old,
132
  sorting: [{ id: 'firstName', desc: false }]
133
}));
134
```
135

136
### Core Table Options
137

138
Essential configuration options for table creation.
139

140
```typescript { .api }
141
interface CoreOptions<TData extends RowData> {
142
  /** The data for the table */
143
  data: TData[];
144
  /** Column definitions */
145
  columns: ColumnDef<TData, any>[];
146
  /** Set this option to override any autoReset feature options */
147
  autoResetAll?: boolean;
148
  /** Enable debug output for all features */
149
  debugAll?: boolean;
150
  /** Enable debug output for columns */
151
  debugColumns?: boolean;
152
  /** Enable debug output for headers */
153
  debugHeaders?: boolean;
154
  /** Enable debug output for rows */
155
  debugRows?: boolean;
156
  /** Enable debug output for table */
157
  debugTable?: boolean;
158
  /** Initial table state */
159
  initialState?: InitialTableState;
160
  /** Get sub rows for expanding functionality */
161
  getSubRows?: (originalRow: TData, index: number) => undefined | TData[];
162
  /** Get row ID from original data */
163
  getRowId?: (originalRow: TData, index: number, parent?: Row<TData>) => string;
164
  /** Meta information that can be accessed anywhere */
165
  meta?: TableMeta<TData>;
166
  /** State change handler */
167
  onStateChange?: OnChangeFn<TableState>;
168
  /** Render fallback for when no data is available */
169
  renderFallbackValue?: any;
170
  /** Array of extra features for the table */
171
  _features?: TableFeature[];
172
}
173
```
174

175
### Table State Management
176

177
The table state contains all feature states and can be controlled externally.
178

179
```typescript { .api }
180
interface TableState extends 
181
  CoreTableState,
182
  VisibilityTableState,
183
  ColumnOrderTableState,
184
  ColumnPinningTableState,
185
  RowPinningTableState,
186
  ColumnFiltersTableState,
187
  GlobalFilterTableState,
188
  SortingTableState,
189
  GroupingTableState,
190
  ExpandedTableState,
191
  PaginationTableState,
192
  RowSelectionTableState,
193
  ColumnSizingTableState {}
194

195
interface InitialTableState extends 
196
  Partial<VisibilityTableState>,
197
  Partial<ColumnOrderTableState>,
198
  Partial<ColumnPinningTableState>,
199
  Partial<RowPinningTableState>,
200
  Partial<ColumnFiltersTableState>,
201
  Partial<GlobalFilterTableState>,
202
  Partial<SortingTableState>,
203
  Partial<GroupingTableState>,
204
  Partial<ExpandedTableState>,
205
  PaginationInitialTableState,
206
  Partial<RowSelectionTableState>,
207
  Partial<ColumnSizingTableState> {}
208
```
209

210
**Usage Examples:**
211

212
```typescript
213
// Controlled state example
214
const [sorting, setSorting] = useState([]);
215
const [columnFilters, setColumnFilters] = useState([]);
216

217
const table = createTable({
218
  data,
219
  columns,
220
  state: {
221
    sorting,
222
    columnFilters,
223
  },
224
  onSortingChange: setSorting,
225
  onColumnFiltersChange: setColumnFilters,
226
  getCoreRowModel: getCoreRowModel(),
227
  getSortedRowModel: getSortedRowModel(),
228
  getFilteredRowModel: getFilteredRowModel(),
229
});
230

231
// Initial state example
232
const table = createTable({
233
  data,
234
  columns,
235
  initialState: {
236
    sorting: [{ id: 'firstName', desc: false }],
237
    columnVisibility: { age: false },
238
    pagination: { pageIndex: 0, pageSize: 10 },
239
  },
240
  getCoreRowModel: getCoreRowModel(),
241
});
242
```
243

244
### Table Features
245

246
The table uses a plugin-based feature system. Each feature extends the core functionality.
247

248
```typescript { .api }
249
interface TableFeature<TData extends RowData = any> {
250
  getDefaultColumnDef?: () => Partial<ColumnDef<TData, unknown>>;
251
  getInitialState?: (state?: InitialTableState) => Partial<InitialTableState>;
252
  getDefaultOptions?: <TData extends RowData>(
253
    table: Table<TData>
254
  ) => Partial<TableOptionsResolved<TData>>;
255
  createTable?: <TData extends RowData>(table: Table<TData>) => void;
256
  getRowId?: (originalRow: TData, index: number, parent?: Row<TData>) => string;
257
}
258
```
259

260
Built-in features include: Headers, ColumnVisibility, ColumnOrdering, ColumnPinning, ColumnFaceting, ColumnFiltering, GlobalFaceting, GlobalFiltering, RowSorting, ColumnGrouping, RowExpanding, RowPagination, RowPinning, RowSelection, ColumnSizing.
261

262
### Meta Information
263

264
Custom metadata that can be attached to the table instance and accessed throughout the API.
265

266
```typescript { .api }
267
interface TableMeta<TData extends RowData> {
268
  /** Any custom data you want to associate with the table */
269
  [key: string]: any;
270
}
271
```
272

273
**Usage Example:**
274

275
```typescript
276
const table = createTable({
277
  data,
278
  columns,
279
  meta: {
280
    updateData: (rowIndex: number, columnId: string, value: any) => {
281
      // Custom update logic
282
    },
283
    deleteRow: (rowIndex: number) => {
284
      // Custom delete logic
285
    },
286
  },
287
  getCoreRowModel: getCoreRowModel(),
288
});
289

290
// Access meta in column definitions or elsewhere
291
const meta = table.options.meta;
292
```