Chapter 53: State Types Reference

Core Idea

Every feature's state slice has a dedicated exported type — prefer these over hand-rolled shapes whenever declaring local React state, an external atom, or a shared type for a state slice, since they stay in sync with the actual runtime shape across TanStack Table versions.

Reference Tables

Type	Shape	Feature
ColumnFilter / ColumnFiltersState	{ id, value } / ColumnFilter[]	Column Filtering
ColumnOrderState	string[] (column ids)	Column Ordering
ColumnPinningState / ColumnPinningPosition	{ start: string[], end: string[] } / 'start' | 'end' | false	Column Pinning
ColumnResizeDirection	'ltr' | 'rtl'	Column Resizing
ColumnResizeMode	'onChange' | 'onEnd'	Column Resizing
columnResizingState	transient drag info (deltaOffset, isResizingColumn, ...)	Column Resizing
ColumnSizingState	Record<columnId, number>	Column Sizing
ColumnVisibilityState	Record<columnId, boolean>	Column Visibility
ColumnSort / SortingState	{ id, desc } / ColumnSort[]	Sorting
SortDirection	'asc' | 'desc'	Sorting
ExpandedState	true | Record<rowId, boolean>	Expanding
GroupingState	string[] (column ids)	Grouping
PaginationState	{ pageIndex, pageSize }	Pagination
RowPinningState / RowPinningPosition	{ top: string[], bottom: string[] } / 'top' | 'bottom' | false	Row Pinning
RowSelectionState	Record<rowId, boolean>	Row Selection
CellSelectionState	Array<{ anchorRowId, anchorColumnId, focusRowId, focusColumnId, operation? }>	Cell Selection

Key Concepts

• AggregationFnOption / FilterFnOption / SortFnOption: the per-TFeatures-typed union of valid string values for aggregationFn/filterFn/sortFn column options — a registered name from the matching registry, 'auto' where applicable, or an inline function. This is the mechanism that makes filterFn: 'notRegistered' a compile error.
• AggregationResult<TOption, TFeatures>: the resolved return-value type for column.getAggregationValue(), varying by whether aggregationFn was a single value (scalar result) or an array (keyed object result) — see Aggregation Guide.
• Every state type here is exactly what an external atom (useCreateAtom<T>(...)) or classic useState<T>(...) should be typed with when owning that slice yourself.

Key Takeaways

1. Always import the feature's dedicated state type rather than inferring/duplicating the shape by hand — these types are the contract, and match exactly what table.state.<slice> and atoms.<slice> expect.
2. *Position types (ColumnPinningPosition, RowPinningPosition) are the small per-item union ('start' | 'end' | false, 'top' | 'bottom' | false) distinct from the full state object — used by column.getIsPinned()/row.getIsPinned()'s return type, not the state itself.
3. CellSelectionState's operation-log shape (not a per-cell map) is the one state type here that doesn't follow the simple "map or array of ids" pattern — see the Cell Selection Guide for why.

Connects To

• Every feature guide chapter (Column Filtering through Cell Selection) for the practical meaning of each state slice.
• Table State (React) Guide: how these types plug into atoms/state/initialState.