Overview TanStack Table is a headless UI library for building data tables and datagrids. It provides logic for sorting, filtering, pagination, grouping, expanding, column pinning/ordering/visibility/resizing, and row selection - without rendering any markup or styles. Package: @tanstack/react-table Utilities: @tanstack/match-sorter-utils (fuzzy filtering) Current Version: v8 Installation npm install @tanstack/react-table Core Architecture Building Blocks Column Definitions - describe columns (data access, rendering, features) Table Instance - central coordinator with state and APIs Row Models - data processing pipeline (filter -> sort -> group -> paginate) Headers, Rows, Cells - renderable units Critical: Data & Column Stability // WRONG - new references every render, causes infinite loops const table = useReactTable ( { data : fetchedData . results , // new ref! columns : [ { accessorKey : 'name' } ] , // new ref! } ) // CORRECT - stable references const columns = useMemo ( ( ) => [ ... ] , [ ] ) const data = useMemo ( ( ) => fetchedData ?. results ?? [ ] , [ fetchedData ] ) const table = useReactTable ( { data , columns , getCoreRowModel : getCoreRowModel ( ) } ) Column Definitions Using createColumnHelper (Recommended) import { createColumnHelper } from '@tanstack/react-table' type Person = { firstName : string lastName : string age : number status : 'active' | 'inactive' } const columnHelper = createColumnHelper < Person
( ) const columns = [ // Accessor column (data column) columnHelper . accessor ( 'firstName' , { header : 'First Name' , cell : info => info . getValue ( ) , footer : info => info . column . id , } ) , // Accessor with function columnHelper . accessor ( row => row . lastName , { id : 'lastName' , // required with accessorFn header : ( ) => < span
Last Name < / span
, cell : info => < i
{ info . getValue ( ) } < / i
, } ) , // Display column (no data, custom rendering) columnHelper . display ( { id : 'actions' , header : 'Actions' , cell : ( { row } ) => ( < button onClick = { ( ) => deleteRow ( row . original ) }
Delete < / button
) , } ) , // Group column (nested headers) columnHelper . group ( { id : 'info' , header : 'Info' , columns : [ columnHelper . accessor ( 'age' , { header : 'Age' } ) , columnHelper . accessor ( 'status' , { header : 'Status' } ) , ] , } ) , ] Column Options Option Type Description id string Unique identifier (auto-derived from accessorKey) accessorKey string Dot-notation path to row data accessorFn (row) => any Custom accessor function header string | (context) => ReactNode Header renderer cell (context) => ReactNode Cell renderer footer (context) => ReactNode Footer renderer size number Default width (default: 150) minSize number Min width (default: 20) maxSize number Max width enableSorting boolean Enable sorting sortingFn string | SortingFn Sort function enableFiltering boolean Enable filtering filterFn string | FilterFn Filter function enableGrouping boolean Enable grouping aggregationFn string | AggregationFn Aggregation function enableHiding boolean Enable visibility toggle enableResizing boolean Enable resizing enablePinning boolean Enable pinning meta any Custom metadata Table Instance Creating a Table import { useReactTable , getCoreRowModel , getSortedRowModel , getFilteredRowModel , getPaginationRowModel , flexRender , } from '@tanstack/react-table' function MyTable ( ) { const [ sorting , setSorting ] = useState < SortingState
( [ ] ) const [ columnFilters , setColumnFilters ] = useState < ColumnFiltersState
( [ ] ) const [ pagination , setPagination ] = useState < PaginationState
( { pageIndex : 0 , pageSize : 10 , } ) const table = useReactTable ( { data , columns , state : { sorting , columnFilters , pagination } , onSortingChange : setSorting , onColumnFiltersChange : setColumnFilters , onPaginationChange : setPagination , getCoreRowModel : getCoreRowModel ( ) , getSortedRowModel : getSortedRowModel ( ) , getFilteredRowModel : getFilteredRowModel ( ) , getPaginationRowModel : getPaginationRowModel ( ) , } ) return ( < table
< thead
{ table . getHeaderGroups ( ) . map ( headerGroup => ( < tr key = { headerGroup . id }
{ headerGroup . headers . map ( header => ( < th key = { header . id } onClick = { header . column . getToggleSortingHandler ( ) }
{ header . isPlaceholder ? null : flexRender ( header . column . columnDef . header , header . getContext ( ) ) } { { asc : ' ↑' , desc : ' ↓' } [ header . column . getIsSorted ( ) as string ] ?? null } < / th
) ) } < / tr
) ) } < / thead
< tbody
{ table . getRowModel ( ) . rows . map ( row => ( < tr key = { row . id }
{ row . getVisibleCells ( ) . map ( cell => ( < td key = { cell . id }
{ flexRender ( cell . column . columnDef . cell , cell . getContext ( ) ) } < / td
) ) } < / tr
) ) } < / tbody
< / table
) } Sorting const table = useReactTable ( { state : { sorting } , onSortingChange : setSorting , getSortedRowModel : getSortedRowModel ( ) , enableSorting : true , enableMultiSort : true , // manualSorting: true, // For server-side sorting } ) // Built-in sort functions: 'alphanumeric', 'text', 'datetime', 'basic' // Column-level: sortingFn: 'alphanumeric' Filtering Column Filtering const table = useReactTable ( { state : { columnFilters } , onColumnFiltersChange : setColumnFilters , getFilteredRowModel : getFilteredRowModel ( ) , getFacetedRowModel : getFacetedRowModel ( ) , getFacetedUniqueValues : getFacetedUniqueValues ( ) , getFacetedMinMaxValues : getFacetedMinMaxValues ( ) , } ) // Built-in: 'includesString', 'equalsString', 'arrIncludes', 'inNumberRange', etc. // Filter UI function Filter ( { column } ) { return ( < input value = { ( column . getFilterValue ( ) ?? '' ) as string } onChange = { e => column . setFilterValue ( e . target . value ) } placeholder = {
Filter... ( ${ column . getFacetedUniqueValues ( ) ?. size } )} /) } Global Filtering const [ globalFilter , setGlobalFilter ] = useState ( '' ) const table = useReactTable ( { state : { globalFilter } , onGlobalFilterChange : setGlobalFilter , globalFilterFn : 'includesString' , getFilteredRowModel : getFilteredRowModel ( ) , } ) Fuzzy Filtering import { rankItem } from '@tanstack/match-sorter-utils' const fuzzyFilter : FilterFn < any
= ( row , columnId , value , addMeta ) => { const itemRank = rankItem ( row . getValue ( columnId ) , value ) addMeta ( { itemRank } ) return itemRank . passed } const table = useReactTable ( { filterFns : { fuzzy : fuzzyFilter } , globalFilterFn : 'fuzzy' , } ) Pagination const table = useReactTable ( { state : { pagination } , onPaginationChange : setPagination , getPaginationRowModel : getPaginationRowModel ( ) , // For server-side: // manualPagination: true, // pageCount: serverPageCount, } ) // Navigation table . nextPage ( ) table . previousPage ( ) table . firstPage ( ) table . lastPage ( ) table . setPageSize ( 20 ) table . getCanNextPage ( ) // boolean table . getCanPreviousPage ( ) // boolean table . getPageCount ( ) // total pages Row Selection const [ rowSelection , setRowSelection ] = useState < RowSelectionState
( { } ) const table = useReactTable ( { state : { rowSelection } , onRowSelectionChange : setRowSelection , enableRowSelection : true , enableMultiRowSelection : true , } ) // Checkbox column columnHelper . display ( { id : 'select' , header : ( { table } ) => ( < input type = "checkbox" checked = { table . getIsAllRowsSelected ( ) } onChange = { table . getToggleAllRowsSelectedHandler ( ) } /
) , cell : ( { row } ) => ( < input type = "checkbox" checked = { row . getIsSelected ( ) } disabled = { ! row . getCanSelect ( ) } onChange = { row . getToggleSelectedHandler ( ) } /
) , } ) // Get selected rows table . getSelectedRowModel ( ) . rows Column Visibility const [ columnVisibility , setColumnVisibility ] = useState < VisibilityState
( { } ) const table = useReactTable ( { state : { columnVisibility } , onColumnVisibilityChange : setColumnVisibility , } ) // Toggle UI { table . getAllLeafColumns ( ) . map ( column => ( < label key = { column . id }
< input type = "checkbox" checked = { column . getIsVisible ( ) } onChange = { column . getToggleVisibilityHandler ( ) } /
{ column . id } < / label
) ) } Column Pinning const [ columnPinning , setColumnPinning ] = useState < ColumnPinningState
( { left : [ 'select' , 'name' ] , right : [ 'actions' ] , } ) const table = useReactTable ( { state : { columnPinning } , onColumnPinningChange : setColumnPinning , enableColumnPinning : true , } ) // Render pinned sections separately row . getLeftVisibleCells ( ) // Left-pinned row . getCenterVisibleCells ( ) // Unpinned row . getRightVisibleCells ( ) // Right-pinned Column Resizing const table = useReactTable ( { enableColumnResizing : true , columnResizeMode : 'onChange' , // 'onChange' | 'onEnd' defaultColumn : { size : 150 , minSize : 50 , maxSize : 500 } , } ) // Resize handle in header < div onMouseDown = { header . getResizeHandler ( ) } onTouchStart = { header . getResizeHandler ( ) } className = {
resizer ${ header . column . getIsResizing ( ) ? 'isResizing' : '' }} /Grouping & Aggregation const [ grouping , setGrouping ] = useState < GroupingState
( [ ] ) const table = useReactTable ( { state : { grouping } , onGroupingChange : setGrouping , getGroupedRowModel : getGroupedRowModel ( ) , getExpandedRowModel : getExpandedRowModel ( ) , } ) // Built-in aggregation: 'sum', 'min', 'max', 'mean', 'median', 'count', 'unique', 'uniqueCount' columnHelper . accessor ( 'amount' , { aggregationFn : 'sum' , aggregatedCell : ( { getValue } ) =>
Total: ${ getValue ( ) }, } ) Row Expanding const [ expanded , setExpanded ] = useState < ExpandedState( { } ) const table = useReactTable ( { state : { expanded } , onExpandedChange : setExpanded , getExpandedRowModel : getExpandedRowModel ( ) , getSubRows : ( row ) => row . subRows , // For hierarchical data } ) // Expand toggle < button onClick = { row . getToggleExpandedHandler ( ) }
{ row . getIsExpanded ( ) ? '−' : '+' } < / button
// Detail row pattern { row . getIsExpanded ( ) && ( < tr
< td colSpan = { columns . length }
< DetailComponent data = { row . original } /
< / td
< / tr
) } Virtualization Integration import { useVirtualizer } from '@tanstack/react-virtual' function VirtualizedTable ( ) { const table = useReactTable ( { / ... / } ) const { rows } = table . getRowModel ( ) const parentRef = useRef < HTMLDivElement
( null ) const virtualizer = useVirtualizer ( { count : rows . length , getScrollElement : ( ) => parentRef . current , estimateSize : ( ) => 35 , overscan : 10 , } ) return ( < div ref = { parentRef } style = { { height : '600px' , overflow : 'auto' } }
< table
< tbody style = { { height :
${ virtualizer . getTotalSize ( ) } px, position : 'relative' } }{ virtualizer . getVirtualItems ( ) . map ( virtualRow => { const row = rows [ virtualRow . index ] return ( < tr key = { row . id } style = { { position : 'absolute' , transform :
translateY( ${ virtualRow . start } px), height :${ virtualRow . size } px, } }{ row . getVisibleCells ( ) . map ( cell => ( < td key = { cell . id }
{ flexRender ( cell . column . columnDef . cell , cell . getContext ( ) ) } < / td
) ) } < / tr
) } ) } < / tbody
< / table
< / div
) } Server-Side Operations const table = useReactTable ( { data : serverData , columns , manualSorting : true , manualFiltering : true , manualPagination : true , pageCount : serverPageCount , state : { sorting , columnFilters , pagination } , onSortingChange : setSorting , onColumnFiltersChange : setColumnFilters , onPaginationChange : setPagination , getCoreRowModel : getCoreRowModel ( ) , // Do NOT include getSortedRowModel, getFilteredRowModel, getPaginationRowModel } ) // Fetch data based on state useEffect ( ( ) => { fetchData ( { sorting , filters : columnFilters , pagination } ) } , [ sorting , columnFilters , pagination ] ) TypeScript Patterns Extending Column Meta declare module '@tanstack/react-table' { interface ColumnMeta < TData extends RowData , TValue
{ filterVariant ? : 'text' | 'range' | 'select' align ? : 'left' | 'center' | 'right' } } Custom Filter/Sort Function Registration declare module '@tanstack/react-table' { interface FilterFns { fuzzy : FilterFn < unknown
} interface SortingFns { myCustomSort : SortingFn < unknown
} } Editable Cells via Table Meta declare module '@tanstack/react-table' { interface TableMeta < TData extends RowData
{ updateData : ( rowIndex : number , columnId : string , value : unknown ) => void } } const table = useReactTable ( { meta : { updateData : ( rowIndex , columnId , value ) => { setData ( old => old . map ( ( row , i ) => i === rowIndex ? { ... row , [ columnId ] : value } : row ) ) } , } , } ) Key Imports import { createColumnHelper , flexRender , useReactTable , getCoreRowModel , getSortedRowModel , getFilteredRowModel , getPaginationRowModel , getGroupedRowModel , getExpandedRowModel , getFacetedRowModel , getFacetedUniqueValues , getFacetedMinMaxValues , } from '@tanstack/react-table' import type { ColumnDef , SortingState , ColumnFiltersState , VisibilityState , PaginationState , ExpandedState , RowSelectionState , GroupingState , ColumnOrderState , ColumnPinningState , FilterFn , SortingFn , } from '@tanstack/react-table' Best Practices Always memoize data and columns to prevent infinite re-renders Use flexRender for all header/cell/footer rendering Use table.getRowModel().rows for final rendered rows (not getCoreRowModel) Import only needed row models - each adds processing to the pipeline Use getRowId for stable row keys when data has unique IDs Use manualX options for server-side operations Pair controlled state with both state.X and onXChange Use module augmentation for custom meta, filter fns, sort fns Use column helper for type-safe column definitions Set autoResetPageIndex: true when filtering should reset pagination Common Pitfalls Defining columns inline (creates new ref each render) Forgetting getCoreRowModel() (required for all tables) Using row models without importing them Not providing id when using accessorFn Mixing manualPagination with client-side getPaginationRowModel Forgetting colSpan for grouped headers Not handling header.isPlaceholder for group column spacers