0
# Column Features
1

2
Advanced column functionality including visibility control, ordering, pinning, and resizing. These features provide comprehensive column management capabilities for building sophisticated table interfaces.
3

4
## Capabilities
5

6
### Column Visibility
7

8
Control which columns are visible or hidden with programmatic and user-driven visibility management.
9

10
```typescript { .api }
11
/** Column visibility state mapping column IDs to visibility */
12
type VisibilityState = Record<string, boolean>;
13

14
interface VisibilityOptions {
15
  /** Visibility state change handler */
16
  onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
17
  /** Enable column hiding globally */
18
  enableHiding?: boolean;
19
  /** Auto reset visibility when columns change */
20
  autoResetColumnVisibility?: boolean;
21
}
22

23
interface VisibilityInstance<TData extends RowData> {
24
  /** Get current visibility state */
25
  getState(): { columnVisibility: VisibilityState };
26
  /** Set column visibility state */
27
  setColumnVisibility(updater: Updater<VisibilityState>): void;
28
  /** Reset column visibility to initial state */
29
  resetColumnVisibility(defaultState?: boolean): void;
30
  /** Get whether all columns are visible */
31
  getIsAllColumnsVisible(): boolean;
32
  /** Get whether some columns are visible */
33
  getIsSomeColumnsVisible(): boolean;
34
  /** Toggle all columns visibility */
35
  toggleAllColumnsVisible(): void;
36
  /** Get visible leaf columns */
37
  getVisibleLeafColumns(): Column<TData, unknown>[];
38
  /** Get left visible leaf columns */
39
  getLeftVisibleLeafColumns(): Column<TData, unknown>[];
40
  /** Get center visible leaf columns */
41
  getCenterVisibleLeafColumns(): Column<TData, unknown>[];
42
  /** Get right visible leaf columns */
43
  getRightVisibleLeafColumns(): Column<TData, unknown>[];
44
}
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { createTable } from "@tanstack/table-core";
51

52
// Basic visibility control
53
const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({
54
  age: false,    // Hide age column
55
  email: false,  // Hide email column
56
});
57

58
const table = createTable({
59
  data,
60
  columns,
61
  getCoreRowModel: getCoreRowModel(),
62
  onColumnVisibilityChange: setColumnVisibility,
63
  state: {
64
    columnVisibility,
65
  },
66
});
67

68
// Toggle specific column visibility
69
const ageColumn = table.getColumn('age');
70
ageColumn.toggleVisibility();
71

72
// Toggle all columns
73
table.toggleAllColumnsVisible();
74

75
// Get visible columns
76
const visibleColumns = table.getVisibleLeafColumns();
77

78
// Column-specific visibility in definition
79
const columns = [
80
  columnHelper.accessor('sensitiveData', {
81
    header: 'Sensitive Data',
82
    enableHiding: false, // Cannot be hidden
83
  }),
84
];
85
```
86

87
### Column Visibility Column Methods
88

89
Methods available on individual columns for visibility management.
90

91
```typescript { .api }
92
interface VisibilityColumn {
93
  /** Get whether this column is visible */
94
  getIsVisible(): boolean;
95
  /** Get whether this column can be hidden */
96
  getCanHide(): boolean;
97
  /** Toggle visibility of this column */
98
  toggleVisibility(value?: boolean): void;
99
}
100
```
101

102
### Column Ordering
103

104
Reorder columns programmatically or through drag-and-drop interfaces.
105

106
```typescript { .api }
107
/** Column order state as array of column IDs */
108
type ColumnOrderState = string[];
109

110
interface ColumnOrderOptions {
111
  /** Column order change handler */
112
  onColumnOrderChange?: OnChangeFn<ColumnOrderState>;
113
  /** Auto reset column order when columns change */
114
  autoResetColumnOrder?: boolean;
115
}
116

117
interface ColumnOrderInstance<TData extends RowData> {
118
  /** Get current column order state */
119
  getState(): { columnOrder: ColumnOrderState };
120
  /** Set column order state */
121
  setColumnOrder(updater: Updater<ColumnOrderState>): void;
122
  /** Reset column order to initial state */
123
  resetColumnOrder(defaultState?: boolean): void;
124
}
125
```
126

127
**Usage Examples:**
128

129
```typescript
130
// Column ordering setup
131
const [columnOrder, setColumnOrder] = useState<ColumnOrderState>([]);
132

133
const table = createTable({
134
  data,
135
  columns,
136
  getCoreRowModel: getCoreRowModel(),
137
  onColumnOrderChange: setColumnOrder,
138
  state: {
139
    columnOrder,
140
  },
141
});
142

143
// Reorder columns programmatically
144
table.setColumnOrder(['lastName', 'firstName', 'age', 'email']);
145

146
// Reset to original order
147
table.resetColumnOrder();
148

149
// Get current order
150
const currentOrder = table.getState().columnOrder;
151
```
152

153
### Column Pinning
154

155
Pin columns to the left or right side of the table for fixed positioning.
156

157
```typescript { .api }
158
/** Column pinning position */
159
type ColumnPinningPosition = 'left' | 'right' | false;
160

161
/** Column pinning state */
162
interface ColumnPinningState {
163
  left?: string[];
164
  right?: string[];
165
}
166

167
interface ColumnPinningOptions {
168
  /** Column pinning change handler */
169
  onColumnPinningChange?: OnChangeFn<ColumnPinningState>;
170
  /** Enable column pinning globally */
171
  enablePinning?: boolean;
172
  /** Auto reset column pinning when columns change */
173
  autoResetColumnPinning?: boolean;
174
}
175

176
interface ColumnPinningInstance<TData extends RowData> {
177
  /** Get current column pinning state */
178
  getState(): { columnPinning: ColumnPinningState };
179
  /** Set column pinning state */
180
  setColumnPinning(updater: Updater<ColumnPinningState>): void;
181
  /** Reset column pinning to initial state */
182
  resetColumnPinning(defaultState?: boolean): void;
183
  /** Get whether any columns are pinned */
184
  getIsSomeColumnsPinned(position?: ColumnPinningPosition): boolean;
185
  /** Get left pinned leaf columns */
186
  getLeftLeafColumns(): Column<TData, unknown>[];
187
  /** Get center (unpinned) leaf columns */
188
  getCenterLeafColumns(): Column<TData, unknown>[];
189
  /** Get right pinned leaf columns */
190
  getRightLeafColumns(): Column<TData, unknown>[];
191
}
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
// Column pinning setup
198
const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({
199
  left: ['select', 'name'],
200
  right: ['actions'],
201
});
202

203
const table = createTable({
204
  data,
205
  columns,
206
  getCoreRowModel: getCoreRowModel(),
207
  onColumnPinningChange: setColumnPinning,
208
  state: {
209
    columnPinning,
210
  },
211
});
212

213
// Pin/unpin columns
214
const nameColumn = table.getColumn('name');
215
nameColumn.pin('left');
216
nameColumn.pin('right');
217
nameColumn.pin(false); // Unpin
218

219
// Get pinned columns
220
const leftColumns = table.getLeftLeafColumns();
221
const centerColumns = table.getCenterLeafColumns();
222
const rightColumns = table.getRightLeafColumns();
223
```
224

225
### Column Pinning Column Methods
226

227
Methods available on individual columns for pinning management.
228

229
```typescript { .api }
230
interface ColumnPinningColumn {
231
  /** Get current pin position of this column */
232
  getIsPinned(): ColumnPinningPosition;
233
  /** Get pin index of this column */
234
  getPinnedIndex(): number;
235
  /** Get whether this column can be pinned */
236
  getCanPin(): boolean;
237
  /** Pin this column to specified position */
238
  pin(position: ColumnPinningPosition): void;
239
}
240
```
241

242
### Column Sizing
243

244
Resize columns with mouse drag or programmatic control.
245

246
```typescript { .api }
247
/** Column sizing state mapping column IDs to widths */
248
type ColumnSizingState = Record<string, number>;
249

250
/** Column resize mode */
251
type ColumnResizeMode = 'onChange' | 'onEnd';
252

253
/** Column resize direction */
254
type ColumnResizeDirection = 'ltr' | 'rtl';
255

256
/** Column sizing info state for tracking resize operations */
257
interface ColumnSizingInfoState {
258
  startOffset: null | number;
259
  startSize: null | number;
260
  deltaOffset: null | number;
261
  deltaPercentage: null | number;
262
  isResizingColumn: false | string;
263
  columnSizingStart: [string, number][];
264
}
265

266
interface ColumnSizingOptions {
267
  /** Column sizing change handler */
268
  onColumnSizingChange?: OnChangeFn<ColumnSizingState>;
269
  /** Column sizing info change handler */
270
  onColumnSizingInfoChange?: OnChangeFn<ColumnSizingInfoState>;
271
  /** Enable column resizing globally */
272
  enableColumnResizing?: boolean;
273
  /** Column resize mode */
274
  columnResizeMode?: ColumnResizeMode;
275
  /** Column resize direction */
276
  columnResizeDirection?: ColumnResizeDirection;
277
  /** Auto reset column sizing when columns change */
278
  autoResetColumnSizing?: boolean;
279
  /** Default column sizing configuration */
280
  defaultColumn?: Partial<ColumnDefBase<any, any>>;
281
}
282
```
283

284
**Usage Examples:**
285

286
```typescript
287
// Column sizing setup
288
const [columnSizing, setColumnSizing] = useState<ColumnSizingState>({});
289

290
const table = createTable({
291
  data,
292
  columns,
293
  getCoreRowModel: getCoreRowModel(),
294
  onColumnSizingChange: setColumnSizing,
295
  state: {
296
    columnSizing,
297
  },
298
  enableColumnResizing: true,
299
  columnResizeMode: 'onChange',
300
  defaultColumn: {
301
    minSize: 50,
302
    maxSize: 500,
303
    size: 150,
304
  },
305
});
306

307
// Set column size programmatically
308
table.getColumn('name')?.resetSize();
309
table.getColumn('name')?.setSize(200);
310

311
// Column sizing in definition
312
const columns = [
313
  columnHelper.accessor('description', {
314
    header: 'Description',
315
    size: 300,
316
    minSize: 200,
317
    maxSize: 600,
318
    enableResizing: true,
319
  }),
320
];
321
```
322

323
### Column Sizing Instance Methods
324

325
Methods available on the table and columns for sizing management.
326

327
```typescript { .api }
328
interface ColumnSizingInstance {
329
  /** Get current column sizing state */
330
  getState(): { columnSizing: ColumnSizingState; columnSizingInfo: ColumnSizingInfoState };
331
  /** Set column sizing state */
332
  setColumnSizing(updater: Updater<ColumnSizingState>): void;
333
  /** Set column sizing info */
334
  setColumnSizingInfo(updater: Updater<ColumnSizingInfoState>): void;
335
  /** Reset column sizing to initial state */
336
  resetColumnSizing(defaultState?: boolean): void;
337
  /** Reset header size info */
338
  resetHeaderSizeInfo(defaultState?: boolean): void;
339
  /** Get total table size */
340
  getTotalSize(): number;
341
  /** Get left table size */
342
  getLeftTotalSize(): number;
343
  /** Get center table size */
344
  getCenterTotalSize(): number;
345
  /** Get right table size */
346
  getRightTotalSize(): number;
347
}
348

349
interface ColumnSizingColumn {
350
  /** Get current size of this column */
351
  getSize(): number;
352
  /** Get start size when resizing */
353
  getStart(): number;
354
  /** Get whether this column is being resized */
355
  getIsResizing(): boolean;
356
  /** Get whether this column can be resized */
357
  getCanResize(): boolean;
358
  /** Reset size of this column */
359
  resetSize(): void;
360
  /** Set size of this column */
361
  setSize(size: number): void;
362
}
363

364
interface ColumnSizingHeader {
365
  /** Get resize handler for this header */
366
  getResizeHandler(): (event: unknown) => void;
367
  /** Get current size of this header */
368
  getSize(): number;
369
  /** Get start position for resizing */
370
  getStart(): number;
371
  /** Get whether this header is being resized */
372
  getIsResizing(): boolean;
373
  /** Get whether this header can be resized */
374
  getCanResize(): boolean;
375
  /** Reset size of this header */
376
  resetSize(): void;
377
}
378
```
379

380
**Usage Examples:**
381

382
```typescript
383
// Table-level sizing methods
384
const totalWidth = table.getTotalSize();
385
const leftWidth = table.getLeftTotalSize();
386

387
// Column-level sizing methods
388
const nameColumn = table.getColumn('name');
389
const nameWidth = nameColumn.getSize();
390
const isResizing = nameColumn.getIsResizing();
391

392
// Header resize handler
393
const nameHeader = table.getHeaderGroups()[0].headers.find(h => h.id === 'name');
394
const resizeHandler = nameHeader.getResizeHandler();
395

396
// Usage in UI (React example)
397
<div
398
  onMouseDown={resizeHandler}
399
  onTouchStart={resizeHandler}
400
  className="resize-handle"
401
/>
402
```
403

404
### Default Column Sizing
405

406
Default sizing configuration that applies to all columns.
407

408
```typescript { .api }
409
/** Default column sizing configuration */
410
const defaultColumnSizing = {
411
  size: 150,
412
  minSize: 20,
413
  maxSize: Number.MAX_SAFE_INTEGER,
414
};
415

416
/** Check if passive event listeners are supported */
417
function passiveEventSupported(): boolean;
418
```
419

420
### Column Definition Extensions
421

422
Column definition properties for controlling various column features.
423

424
```typescript { .api }
425
interface VisibilityColumnDef {
426
  /** Enable/disable hiding for this column */
427
  enableHiding?: boolean;
428
}
429

430
interface ColumnPinningColumnDef {
431
  /** Enable/disable pinning for this column */
432
  enablePinning?: boolean;
433
}
434

435
interface ColumnSizingColumnDef {
436
  /** Initial size of this column */
437
  size?: number;
438
  /** Minimum size of this column */
439
  minSize?: number;
440
  /** Maximum size of this column */
441
  maxSize?: number;
442
  /** Enable/disable resizing for this column */
443
  enableResizing?: boolean;
444
}
445
```
446

447
**Usage Examples:**
448

449
```typescript
450
// Column definition with all features
451
const columns = [
452
  columnHelper.accessor('name', {
453
    header: 'Name',
454
    size: 200,
455
    minSize: 100,
456
    maxSize: 300,
457
    enableHiding: false,     // Cannot be hidden
458
    enablePinning: true,     // Can be pinned
459
    enableResizing: true,    // Can be resized
460
  }),
461
  columnHelper.display({
462
    id: 'actions',
463
    header: 'Actions',
464
    size: 100,
465
    enableHiding: false,
466
    enablePinning: true,
467
    enableResizing: false,   // Fixed width
468
    cell: ({ row }) => (
469
      <button onClick={() => handleEdit(row.original)}>
470
        Edit
471
      </button>
472
    ),
473
  }),
474
];
475
```