react-client-to-server

name	react/client-to-server
description	Convert a client-side `@tanstack/react-table` v9 table to server-side (manual modes). Pass server-paginated/sorted/filtered rows as `data`, set `manualPagination` / `manualSorting` / `manualFiltering` / `manualGrouping` / `manualExpanding` for whatever the server now owns, supply `rowCount` so `getPageCount()` works, and DROP the matching factory from `tableFeatures()` (no `paginatedRowModel` slot if the server paginates). Own the relevant state slices via external atoms (`useCreateAtom` + `options.atoms`) so a query can key on the slice and refetch automatically — OR via classic `state` + `on*Change` controlled state.
type	lifecycle
library	tanstack-table
framework	react
library_version	9.0.0-alpha.48
requires	["state-management","pagination","filtering","sorting","react/table-state"]
sources	["TanStack/table:examples/react/basic-external-atoms/src/main.tsx","TanStack/table:examples/react/with-tanstack-query/src/main.tsx","TanStack/table:examples/react/with-tanstack-query/src/fetchData.ts"]

This skill builds on tanstack-table/state-management and tanstack-table/react/table-state. Read those first — the atom model is what makes the cleanest server-side wiring possible.

Why "client-to-server"

A client-side table sees every row, sorts/filters/paginates them locally, and renders a slice. A server-side table sees only the slice the server returned for the current request; the table must be told "don't try to slice this again — and here's the total row count so you can render a pager".

Four moves convert any client table to a server table:

1. manualX: true for whichever operations the server owns.
2. Drop the matching factory from tableFeatures() so it doesn't ship in your bundle.
3. Provide rowCount so table.getPageCount() / getCanNextPage() work.
4. Own the slice state externally so your data fetcher can key on it.

Setup

Two state-ownership patterns work; pick one per slice.

Pattern A — external atom (cleanest with Query/SWR)

import * as React from 'react'
import { useCreateAtom, useSelector } from '@tanstack/react-store'
import {
  useTable,
  tableFeatures,
  rowPaginationFeature,
  createColumnHelper,
} from '@tanstack/react-table'
import type { PaginationState } from '@tanstack/react-table'

const features = tableFeatures({ rowPaginationFeature })
const columnHelper = createColumnHelper<typeof features, Person>()
const columns = columnHelper.columns([
  columnHelper.accessor('firstName', { header: 'First' }),
  columnHelper.accessor('age', { header: 'Age' }),
])

const EMPTY: Person[] = []

function ServerTable() {
  // 1) Own pagination in an external atom.
  const paginationAtom = useCreateAtom<PaginationState>({
    pageIndex: 0,
    pageSize: 10,
  })
  const pagination = useSelector(paginationAtom)

  // 2) Fetch keyed on the atom value.
  const [serverPage, setServerPage] = React.useState<{
    rows: Person[]
    rowCount: number
  } | null>(null)
  React.useEffect(() => {
    let cancelled = false
    fetchPeople(pagination).then((page) => {
      if (!cancelled) setServerPage(page)
    })
    return () => {
      cancelled = true
    }
  }, [pagination])

  // 3) Manual pagination + rowCount. No paginatedRowModel in features.
  const table = useTable({
    features,
    columns,
    data: serverPage?.rows ?? EMPTY, // EMPTY at module scope
    rowCount: serverPage?.rowCount,
    atoms: { pagination: paginationAtom }, // table writes here directly
    manualPagination: true,
  })
  // No onPaginationChange — table.setPageIndex(...) writes through the atom.
}

Source: examples/react/basic-external-atoms/src/main.tsx (atoms wiring); examples/react/with-tanstack-query/src/main.tsx (rowCount + manualPagination).

Pattern B — classic state + on*Change

const [pagination, setPagination] = React.useState<PaginationState>({
  pageIndex: 0,
  pageSize: 10,
})

const table = useTable({
  features,
  columns,
  data: serverPage?.rows ?? EMPTY,
  rowCount: serverPage?.rowCount,
  state: { pagination },
  onPaginationChange: setPagination, // REQUIRED with state.pagination
  manualPagination: true,
})

Both work. state + on*Change is familiar from v8; atoms compose more cleanly with Query (the table writes to the atom, the query key includes the atom value, the query refetches automatically).

Core Patterns

Combining server-side sort + filter + pagination

Add the matching manual* flags for each operation the server now owns. Local features (column visibility, ordering, pinning) still work because they don't depend on the row model.

const features = tableFeatures({
  rowSortingFeature,
  rowPaginationFeature,
  columnFilteringFeature,
  columnVisibilityFeature, // still local
  columnPinningFeature, // still local
})

const sortingAtom = useCreateAtom<SortingState>([])
const paginationAtom = useCreateAtom<PaginationState>({
  pageIndex: 0,
  pageSize: 10,
})
const columnFiltersAtom = useCreateAtom<ColumnFiltersState>([])

const sorting = useSelector(sortingAtom)
const pagination = useSelector(paginationAtom)
const columnFilters = useSelector(columnFiltersAtom)

const serverArgs = { sorting, pagination, columnFilters }
// ... fetch keyed on serverArgs

const table = useTable({
  features, // no sorted/filtered/paginated factories — server owns them
  columns,
  data: serverPage?.rows ?? EMPTY,
  rowCount: serverPage?.rowCount,
  atoms: {
    sorting: sortingAtom,
    pagination: paginationAtom,
    columnFilters: columnFiltersAtom,
  },
  manualSorting: true,
  manualFiltering: true,
  manualPagination: true,
})

Source: examples/react/basic-external-atoms/src/main.tsx.

When NOT to manual-mode a slice

If the server returns the entire dataset, leave the table client-side. Manual mode is for slices the server has already trimmed.

Common Mistakes

CRITICAL Forgetting manualPagination / manualSorting / manualFiltering

Wrong:

const features = tableFeatures({
  rowPaginationFeature,
  paginatedRowModel: createPaginatedRowModel(), // factory registered — but server already paginated
})
const table = useTable({
  features,
  columns,
  data: serverPage.rows,
  // missing manualPagination
})

Correct:

const features = tableFeatures({
  rowPaginationFeature,
  // no paginatedRowModel — server paginates
})
const table = useTable({
  features,
  columns,
  data: serverPage.rows,
  rowCount: serverPage.rowCount,
  manualPagination: true,
})

Without manualPagination: true, the table tries to slice the already-server-sliced page a second time, producing rows that don't exist (or visibly wrong pagination). Source: examples/react/with-tanstack-query/src/main.tsx.

CRITICAL Missing rowCount

Wrong:

const table = useTable({
  features,
  columns,
  data: serverPage.rows,
  manualPagination: true,
  // missing rowCount: serverPage.totalRowCount
})
// table.getPageCount() → 1, pager locks at "Page 1 of 1"

Correct:

const table = useTable({
  features,
  columns,
  data: serverPage.rows,
  rowCount: serverPage.rowCount, // ← required for accurate pager
  manualPagination: true,
})

Without rowCount, getPageCount() falls back to Math.ceil(data.length / pageSize) — which is 1 if the server returned a single page. Source: examples/react/with-tanstack-query/src/main.tsx.

HIGH state.pagination without onPaginationChange

Wrong:

const [pagination] = React.useState<PaginationState>({
  pageIndex: 0,
  pageSize: 10,
})
useTable({
  features,
  columns,
  data,
  state: { pagination },
  // missing onPaginationChange — table.setPageIndex is a no-op
  manualPagination: true,
})

Correct:

const [pagination, setPagination] = React.useState<PaginationState>({
  pageIndex: 0,
  pageSize: 10,
})
useTable({
  features,
  columns,
  data,
  state: { pagination },
  onPaginationChange: setPagination, // ← required
  manualPagination: true,
})
// OR — use atoms.pagination instead, which doesn't need a writeback handler.

The library treats state as controlled; without a writeback handler, table.setPageIndex(...) writes nowhere. Source: docs/framework/react/guide/table-state.md.

HIGH Leaving paginatedRowModel registered for a server-paginated table

Wrong:

const features = tableFeatures({
  rowPaginationFeature,
  paginatedRowModel: createPaginatedRowModel(), // ships for nothing
})
useTable({
  features,
  columns,
  data: serverPage.rows,
  manualPagination: true,
})

Correct:

const features = tableFeatures({
  rowPaginationFeature,
  // drop paginatedRowModel — server owns pagination
})
useTable({
  features,
  columns,
  data: serverPage.rows,
  rowCount: serverPage.rowCount,
  manualPagination: true,
})

The factory ships in your bundle for no reason. Manual mode + the factory will also let the factory re-slice your already-sliced server page if manualPagination is ever flipped off. Source: maintainer guidance.

HIGH Mixing state.X and atoms.X for the same slice

Wrong:

useTable({
  features,
  columns,
  data,
  state: { pagination }, // silently ignored
  onPaginationChange: setPagination, // silently ignored
  atoms: { pagination: paginationAtom }, // wins
  manualPagination: true,
})

Correct:

// Pick one ownership mechanism per slice.
useTable({
  features,
  columns,
  data,
  atoms: { pagination: paginationAtom },
  manualPagination: true,
})

Precedence is options.atoms[key] > options.state[key] > internal. The state plumbing is dead code in this configuration. Source: examples/react/basic-external-atoms/src/main.tsx.

MEDIUM Recreating data array identity in JSX

Wrong:

<MyTable data={query.data?.rows ?? []} columns={columns} />
// `?? []` produces a new array reference each render → internal memos bust

Correct:

const EMPTY: Person[] = []   // module scope

<MyTable data={query.data?.rows ?? EMPTY} columns={columns} />
// or wrap in useMemo

Internal memoization keys off identity. A fresh [] each render bypasses memos and may force re-computation. Source: maintainer guidance; examples/react/with-tanstack-query/src/main.tsx.

See Also

• tanstack-table/react/compose-with-tanstack-query — the canonical Query + server-side pattern.
• tanstack-table/react/compose-with-tanstack-store — sharing slice atoms across components.
• tanstack-table/react/table-state — selectors, <Subscribe>, external atoms.
• tanstack-table/react/production-readiness — when to narrow selectors as the table grows.