TanStack Table Patterns

Quick Guide: TanStack Table is a headless UI library for building powerful tables and datagrids. Use

useReactTable

hook with

createColumnHelper

for type-safe column definitions. Import only the row models you need (

getSortedRowModel

,

getFilteredRowModel

, etc.) for tree-shaking. Memoize data and columns with

useMemo

to prevent infinite re-renders. Set

manualPagination

,

manualSorting

,

manualFiltering

to

true

for server-side data.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

(You MUST memoize data and columns with

useMemo

(You MUST use

createColumnHelper<TData>()

(You MUST import row models explicitly -

getSortedRowModel

getFilteredRowModel

(You MUST use

accessorKey

accessorFn

id

(You MUST set

manualPagination

manualSorting

manualFiltering

true

</critical_requirements>

Auto-detection: TanStack Table, @tanstack/react-table, useReactTable, createColumnHelper, getCoreRowModel, getSortedRowModel, getFilteredRowModel, getPaginationRowModel, ColumnDef, column definitions, table state

When to use:

• Building data tables with sorting, filtering, and pagination
• Implementing server-side data tables with API integration
• Creating tables with row selection and expansion
• Building virtual scrolling tables for large datasets
• Implementing column visibility controls and column ordering

When NOT to use:

• Simple tables without interactive features (use plain HTML tables)
• Tables with fewer than 20 rows and no sorting/filtering needs
• Read-only data display without user interaction

Key patterns covered:

• useReactTable hook setup with type-safe generics
• Column definitions with columnHelper
• Sorting, filtering, pagination (client-side and server-side)
• Row selection, expanding rows, column visibility
• Virtual scrolling, column pinning, column resizing

Detailed Resources:

• examples/core.md - Basic table setup, column definitions, type safety
• examples/sorting.md - Column sorting with custom sort functions
• examples/filtering.md - Column and global filtering
• examples/pagination.md - Client-side pagination
• examples/selection.md - Row selection with bulk actions
• examples/expanding.md - Expandable rows with sub-content
• examples/column-visibility.md - Column visibility toggles
• examples/server-side.md - Server-side data handling
• examples/virtualization.md - Virtual scrolling for large datasets
• examples/column-pinning.md - Sticky pinned columns (left/right)
• examples/column-resizing.md - Performant column resizing with CSS variables
• reference.md - Decision frameworks, checklists, anti-patterns

Philosophy

TanStack Table is a headless UI library - it provides the logic for tables without any markup or styles. This gives you complete control over rendering while the library handles complex state management for sorting, filtering, pagination, and more.

Core Principles:

1. Headless Architecture - No pre-built components. You own the markup and styling.
2. Type Safety - Full TypeScript support with generics for data types.
3. Tree-Shakable - Import only what you use. Each feature is a separate row model.
4. Framework Agnostic - Same API works across React, Vue, Solid, and Svelte.
5. Performant - Optimized for large datasets with virtualization support.

Why Headless?

The headless approach means TanStack Table handles the hard parts (state management, sorting algorithms, pagination logic) while you control presentation. This is ideal when:

• You need custom table designs that don't fit pre-built components
• You're integrating with an existing design system
• You need maximum performance control

Core Patterns

Pattern 1: Basic Table Setup

Set up a type-safe table with

useReactTable

createColumnHelper

const columnHelper = createColumnHelper<User>();

const columns = useMemo(
  () => [
    columnHelper.accessor("firstName", { header: "First Name" }),
    // accessorFn for computed values - MUST include id
    columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
      id: "fullName",
      header: "Full Name",
    }),
  ],
  [],
);

const data = useMemo(() => users, [users]);

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getRowId: (row) => row.id,
});

Critical: Memoize both

columns

data

Pattern 2: Sorting

Enable sorting with

getSortedRowModel

const [sorting, setSorting] = useState<SortingState>([]);

const table = useReactTable({
  data,
  columns,
  state: { sorting },
  onSortingChange: setSorting,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
});

// In column def:
columnHelper.accessor("createdAt", {
  header: "Created",
  sortingFn: "datetime", // Required for Date objects
});

Gotcha: Dates don't sort correctly with default sort. Use

sortingFn: "datetime"

Pattern 3: Filtering

Column filters and global filter with

getFilteredRowModel

const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
const [globalFilter, setGlobalFilter] = useState("");

const table = useReactTable({
  data,
  columns,
  state: { columnFilters, globalFilter },
  onColumnFiltersChange: setColumnFilters,
  onGlobalFilterChange: setGlobalFilter,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
});

Gotcha: Multiple column filters combine with AND logic, not OR. Use global filter or custom logic for OR behavior.

Pattern 4: Pagination

Client-side and server-side pagination with

getPaginationRowModel

const DEFAULT_PAGE_SIZE = 10;

const [pagination, setPagination] = useState<PaginationState>({
  pageIndex: 0,
  pageSize: DEFAULT_PAGE_SIZE,
});

const table = useReactTable({
  data,
  columns,
  state: { pagination },
  onPaginationChange: setPagination,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
});

Gotcha:

pageIndex

Pattern 5: Row Selection

Single and multi-row selection. See examples/selection.md.

const [rowSelection, setRowSelection] = useState<RowSelectionState>({});

const table = useReactTable({
  data,
  columns,
  state: { rowSelection },
  onRowSelectionChange: setRowSelection,
  getCoreRowModel: getCoreRowModel(),
  enableRowSelection: true,
  getRowId: (row) => row.id, // CRITICAL: Stable IDs for selection
});

Critical: Without

getRowId

Pattern 6: Server-Side Data

Handle server-side pagination, sorting, and filtering. See examples/server-side.md.

const table = useReactTable({
  data: apiData ?? [],
  columns,
  state: { pagination, sorting, columnFilters },
  onPaginationChange: setPagination,
  onSortingChange: setSorting,
  onColumnFiltersChange: setColumnFilters,
  getCoreRowModel: getCoreRowModel(),
  // CRITICAL: All three manual flags for server-side
  manualPagination: true,
  manualSorting: true,
  manualFiltering: true,
  rowCount: totalFromApi,
});

Critical: Do NOT import client-side row models (

getSortedRowModel

manual*: true

Pattern 7: Column Visibility

Toggle column visibility. See examples/column-visibility.md.

const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({
  email: false, // Hide by default
});

// In column def - prevent hiding required columns:
columnHelper.accessor("id", { enableHiding: false });

Pattern 8: Expanding Rows

Expandable rows for hierarchical data or detail views. See examples/expanding.md.

const [expanded, setExpanded] = useState<ExpandedState>({});

const table = useReactTable({
  data,
  columns,
  state: { expanded },
  onExpandedChange: setExpanded,
  getCoreRowModel: getCoreRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
  getRowCanExpand: () => true,
});

Pattern 9: Reusable Generic Table Component

Leverage TypeScript generics for a reusable table component. See examples/core.md.

interface DataTableProps<TData, TValue> {
  columns: ColumnDef<TData, TValue>[];
  data: TData[];
}

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  });
  // ... render table
}

Pattern 10: Column Pinning

Keep columns visible during horizontal scroll. See examples/column-pinning.md.

const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({
  left: ["id"],
  right: ["actions"],
});

Critical: Pinning provides state only. You must apply

position: sticky

Pattern 11: Column Resizing

User-adjustable column widths. See examples/column-resizing.md.

const table = useReactTable({
  data,
  columns,
  columnResizeMode: "onChange", // or "onEnd" for simpler, more performant
  enableColumnResizing: true,
});

Critical:

columnResizeMode: "onChange"

"onEnd"

<red_flags>

RED FLAGS

High Priority Issues:

• Missing useMemo on columns/data - Columns or data defined inline without memoization cause infinite re-renders. Must be memoized or defined outside the component.
• accessorFn without id - Using

  accessorFn

  without providing an

  id

  causes runtime errors.
• Missing manualPagination for server-side - Forgetting

  manualPagination: true

  when using server-side data causes the table to paginate already-paginated data.
• Returning JSX from accessorFn - Accessors return primitive values for sorting/filtering. Use the

  cell

  option for JSX rendering.

Medium Priority Issues:

• Not providing rowCount for server-side - Without

  rowCount

  or

  pageCount

  , the table cannot calculate correct page count.
• Missing getRowId with selection - Without

  getRowId

  , row selection uses array indices which break on sort/filter.
• Not using flexRender - Manually rendering header/cell values breaks when columnDef uses a function for header/cell.

Gotchas & Edge Cases:

• Date sorting requires

  sortingFn: "datetime"

  - JavaScript dates don't sort correctly by default
• Column filters are AND, not OR - Multiple column filters combine with AND logic

• pageIndex

  is 0-based - Many APIs use 1-based; add 1 when sending to server

• autoResetPageIndex

  defaults to

  true

  - Page resets to 0 when data changes; set to

  false

  for server-side
• Column pinning requires sticky CSS - TanStack Table provides state only, you apply CSS

• columnResizeMode: "onChange"

  needs CSS variables + memoized body for performance
• Attach

  getResizeHandler

  to both

  onMouseDown

  and

  onTouchStart

  for mobile support
• Pinning affects column order - Pinning, column ordering, and grouping all reorder columns; pinning happens first
• Pinned cells need background color - Otherwise scrolling content shows through

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST memoize data and columns with

useMemo

(You MUST use

createColumnHelper<TData>()

(You MUST import row models explicitly -

getSortedRowModel

getFilteredRowModel

(You MUST use

accessorKey

accessorFn

id

(You MUST set

manualPagination

manualSorting

manualFiltering

true

Failure to follow these rules will cause infinite re-renders, TypeScript errors, and incorrect server-side behavior.

</critical_reminders>