@tanstack/table-core 9.0.0-beta.5 → 9.0.0-beta.51

package/skills/pagination/SKILL.md

@@ -1,385 +1,78 @@
 ---
 name: pagination
 description: >
-  Paginate rows in TanStack Table v9 with the `paginatedRowModel` stage. Covers
-  `rowPaginationFeature` + `createPaginatedRowModel()`, `state.pagination`
-  ({ pageIndex, pageSize }), `onPaginationChange`, `manualPagination`,
-  `rowCount` and `pageCount` for server-side, `autoResetPageIndex`,
-  `paginateExpandedRows`, navigation APIs (`nextPage`/`previousPage`/`firstPage`/
-  `lastPage`/`setPageIndex`/`setPageSize`), `getCanNextPage` / `getCanPreviousPage`,
-  `getPageCount` / `getRowCount` / `getPageOptions`, and `getPrePaginatedRowModel`
-  for "total filtered" counts.
-type: core
-library: tanstack-table
-library_version: '9.0.0-alpha.48'
-requires:
-  - state-management
+  Paginate with rowPaginationFeature and paginatedRowModel or manualPagination. Load for pageIndex/pageSize state, rowCount/pageCount, unknown next-page limits, already-paginated server data, or autoResetPageIndex surprises.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.51',
+  }
+requires: ['core', 'table-features', 'client-vs-server']
 sources:
-  - TanStack/table:docs/guide/pagination.md
-  - TanStack/table:packages/table-core/src/features/row-pagination/rowPaginationFeature.utils.ts
-  - TanStack/table:packages/table-core/src/features/row-pagination/createPaginatedRowModel.ts
-  - TanStack/table:examples/react/pagination/src/main.tsx
+  - 'TanStack/table:docs/framework/react/guide/pagination.md'
+  - 'TanStack/table:packages/table-core/src/features/row-pagination'
+  - 'TanStack/table:examples/react/pagination'
 ---
 
-This skill builds on `tanstack-table/state-management`. Read it first for the atom model and `manual*` mode.
+This skill builds on `core`, `table-features`, and `client-vs-server`. Choose client slicing or server pages, never both accidentally.
 
 ## Setup
 
 ```ts
 import {
-  tableFeatures,
-  rowPaginationFeature,
   createPaginatedRowModel,
-  constructTable,
+  rowPaginationFeature,
+  tableFeatures,
 } from '@tanstack/table-core'
-import type { PaginationState } from '@tanstack/table-core'
-
-const features = tableFeatures({ rowPaginationFeature })
 
-const table = constructTable({
-  features,
-  rowModels: {
-    paginatedRowModel: createPaginatedRowModel(),
-  },
-  columns,
-  data,
-  initialState: {
-    pagination: { pageIndex: 0, pageSize: 10 } satisfies PaginationState,
-  },
+export const features = tableFeatures({
+  rowPaginationFeature,
+  paginatedRowModel: createPaginatedRowModel(),
 })
-
-table.nextPage()
-table.setPageIndex(5)
-table.setPageSize(25)
-table.getCanNextPage()
-table.getPageCount()
-table.getRowCount()
+export const initialState = { pagination: { pageIndex: 0, pageSize: 25 } }
 ```
 
 ## Core Patterns
 
-### Pagination toolbar
-
-```tsx
-// From examples/react/pagination/src/main.tsx
-<div>
-  <button
-    onClick={() => table.firstPage()}
-    disabled={!table.getCanPreviousPage()}
-  >
-    {'<<'}
-  </button>
-  <button
-    onClick={() => table.previousPage()}
-    disabled={!table.getCanPreviousPage()}
-  >
-    {'<'}
-  </button>
-  <button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
-    {'>'}
-  </button>
-  <button onClick={() => table.lastPage()} disabled={!table.getCanNextPage()}>
-    {'>>'}
-  </button>
-
-  <span>
-    Page {table.store.state.pagination.pageIndex + 1} of{' '}
-    {table.getPageCount().toLocaleString()}
-  </span>
-
-  <span>
-    | Go to page:
-    <input
-      type="number"
-      defaultValue={table.store.state.pagination.pageIndex + 1}
-      onChange={(e) => {
-        const page = e.target.value ? Number(e.target.value) - 1 : 0
-        table.setPageIndex(page)
-      }}
-    />
-  </span>
-
-  <select
-    value={table.store.state.pagination.pageSize}
-    onChange={(e) => table.setPageSize(Number(e.target.value))}
-  >
-    {[10, 20, 30, 40, 50].map((size) => (
-      <option key={size} value={size}>
-        Show {size}
-      </option>
-    ))}
-  </select>
-</div>
-```
-
-### Server-side pagination
-
-```tsx
-const [pagination, setPagination] = useState<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-const { data: dataQuery } = useQuery({
-  queryKey: ['rows', pagination],
-  queryFn: () => fetchPage(pagination.pageIndex, pagination.pageSize),
-})
-
-const table = useTable({
-  features: tableFeatures({ rowPaginationFeature }),
-  rowModels: {}, // no paginatedRowModel — server paginates
-  data: dataQuery?.rows ?? EMPTY,
-  columns,
-  manualPagination: true,
-  rowCount: dataQuery?.rowCount, // server-provided total
-  // OR: pageCount: dataQuery.pageCount
-  // OR: pageCount: -1 if unknown (next button stays enabled)
-  state: { pagination },
-  onPaginationChange: setPagination,
-})
-```
-
-### Disable auto page reset when filters change
-
-```ts
-const table = constructTable({
-  features: tableFeatures({ rowPaginationFeature, columnFilteringFeature }),
-  rowModels: {
-    paginatedRowModel: createPaginatedRowModel(),
-    filteredRowModel: createFilteredRowModel(filterFns),
-  },
-  columns,
-  data,
-  autoResetPageIndex: false, // keep current page while user types in a filter
-})
-```
-
-`autoResetPageIndex` defaults to `!manualPagination` — true client-side, false manual.
-
-### "Total filtered rows" display while paginated
-
 ```ts
-const totalFiltered = table.getPrePaginatedRowModel().rows.length
-const onCurrentPage = table.getRowModel().rows.length
+const serverOptions = { manualPagination: true, rowCount: response.total }
 ```
 
-`getPrePaginatedRowModel` is the row model AFTER filtering/sorting/grouping/expansion but BEFORE the page slice.
+Pass one already-processed page and either `rowCount` or `pageCount`.
 
 ## Common Mistakes
 
-### [HIGH] Setting `manualPagination: true` without supplying `rowCount` or `pageCount`
-
-Wrong:
-
-```tsx
-// getPageCount() returns 1, next/prev buttons are disabled
-const table = useTable({
-  features: tableFeatures({ rowPaginationFeature }),
-  rowModels: {},
-  data, // only 10 rows for the current page
-  columns,
-  manualPagination: true,
-  state: { pagination },
-  onPaginationChange: setPagination,
-  // missing: rowCount or pageCount
-})
-```
-
-Correct:
-
-```tsx
-const table = useTable({
-  features: tableFeatures({ rowPaginationFeature }),
-  rowModels: {},
-  data: dataQuery.rows,
-  columns,
-  manualPagination: true,
-  rowCount: dataQuery.rowCount, // server tells the table the total
-  // OR: pageCount: dataQuery.pageCount
-  // OR: pageCount: -1 if unknown
-  state: { pagination },
-  onPaginationChange: setPagination,
-})
-```
-
-`getRowCount()` defaults to `getPrePaginatedRowModel().rows.length` — which in manual mode is only the current page. Without `rowCount`/`pageCount`, the table thinks there's one page total.
-
-Source: packages/table-core/src/features/row-pagination/rowPaginationFeature.utils.ts
-
-### [MEDIUM] Putting `pagination` in BOTH `state` and `initialState`
-
-Wrong:
-
-```tsx
-const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })
-const table = useTable({
-  initialState: { pagination: { pageSize: 25 } }, // IGNORED
-  state: { pagination }, // wins (pageSize 10)
-  onPaginationChange: setPagination,
-})
-```
-
-Correct:
-
-```tsx
-const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 25 })
-const table = useTable({
-  features: tableFeatures({ rowPaginationFeature }),
-  rowModels: { paginatedRowModel: createPaginatedRowModel() },
-  columns,
-  data,
-  state: { pagination },
-  onPaginationChange: setPagination,
-})
-```
-
-`state` always overrides `initialState`. Seed the controlled state in `useState` or use `initialState` alone — never both.
-
-Source: docs/guide/pagination.md
-
-### [MEDIUM] `autoResetPageIndex: false` without manual clamping leaves empty pages
-
-Wrong:
-
-```ts
-const table = useTable({
-  features,
-  rowModels: {
-    paginatedRowModel: createPaginatedRowModel(),
-    filteredRowModel: createFilteredRowModel(filterFns),
-  },
-  columns,
-  data,
-  autoResetPageIndex: false, // user on page 5, then filters down to 2 pages
-  // → page 5 is empty. No automatic clamp.
-})
-```
-
-Correct:
-
-```ts
-// Either leave autoResetPageIndex default (true) for client-side,
-// or clamp manually after a data-altering effect:
-useEffect(() => {
-  const lastPage = Math.max(0, table.getPageCount() - 1)
-  if (table.atoms.pagination.get().pageIndex > lastPage) {
-    table.setPageIndex(lastPage)
-  }
-}, [data, columnFilters])
-```
-
-`setPageIndex` only clamps against `options.pageCount` (max safe int when unset). It doesn't clamp against the current row model.
-
-Source: packages/table-core/src/features/row-pagination/rowPaginationFeature.utils.ts
-
-### [LOW] Expecting `getRowCount()` to equal `data.length` under filtering/grouping/expansion
-
-Wrong:
-
-```ts
-console.log(table.getRowCount()) // count after all transforms
-console.log(data.length) // raw input count
-// These diverge under filtering, grouping, or tree vs flat input.
-```
-
-Correct:
-
-```ts
-table.getCoreRowModel().rows.length // raw row count (flat)
-table.getPreFilteredRowModel().rows.length // before filtering
-table.getFilteredRowModel().rows.length // after filtering
-table.getRowCount() // pre-paginated count (or `rowCount` option in manual mode)
-table.getRowModel().rows.length // current page only
-```
-
-`getRowCount` returns `options.rowCount ?? getPrePaginatedRowModel().rows.length`. Pick the model that matches the question.
+### [CRITICAL] Expecting manual mode to slice
 
-Source: docs/guide/row-models.md
+Wrong: `const options = { data: allRows, manualPagination: true }`
 
-### [HIGH] `getToggleAllRowsSelectedHandler` only selects current page under server pagination
-
-Wrong:
-
-```tsx
-// Header checkbox only affects current page in manualPagination mode
-<input
-  checked={table.getIsAllRowsSelected()}
-  onChange={table.getToggleAllRowsSelectedHandler()}
-/>
-```
+Correct: `const options = { data: requestedPageRows, manualPagination: true, rowCount: totalRows }`
 
-Correct:
+Manual pagination trusts the provided data as the current page.
 
-```tsx
-// Use page-aware APIs with server pagination
-<input
-  checked={table.getIsAllPageRowsSelected()}
-  onChange={table.getToggleAllPageRowsSelectedHandler()}
-/>
-// For "select all server-side rows", track a separate "all rows mode"
-// boolean alongside the row map.
-```
+Source: `https://github.com/TanStack/table/issues/4917`
 
-The table only knows about the current page's rows under `manualPagination`. "Select all" can never mean "every row on the server" without an explicit out-of-band selection mode.
+### [HIGH] Omitting the server total
 
-Source: https://github.com/TanStack/table/issues/4781
+Wrong: `const options = { data: pageRows, manualPagination: true }`
 
-### [MEDIUM] `autoResetPageIndex` resets to `initialState.pageIndex` (not 0)
+Correct: `const options = { data: pageRows, manualPagination: true, rowCount: 1234 }`
 
-Wrong:
+Without a count, last-page and next-page availability cannot reflect the server dataset.
 
-```ts
-// Filtering data resets to the deep-linked pageIndex, not 0
-const table = useTable({
-  data,
-  columns,
-  initialState: { pagination: { pageIndex: 5, pageSize: 10 } },
-  autoResetPageIndex: true,
-})
-```
+Source: `packages/table-core/src/features/row-pagination/rowPaginationFeature.types.ts`
 
-Correct:
+### [HIGH] Fighting automatic page resets
 
-```ts
-useEffect(() => {
-  table.setPageIndex(0)
-}, [columnFilters, globalFilter])
-// Or: don't rely on autoResetPageIndex when deep-linking pageIndex
-```
+Wrong: `onPaginationChange: setPagination`
 
-`_autoResetPageIndex` calls `resetPageIndex()` without `true`, which restores to `initialState.pagination.pageIndex` — typically a URL deep-link page that's now invalid.
-
-Source: https://github.com/TanStack/table/issues/6207
-
-### [CRITICAL] Reimplementing pagination math manually
-
-Wrong:
-
-```ts
-// Hand-rolled page slicing instead of using the API
-const paginatedRows = useMemo(
-  () => allRows.slice(pageIndex * pageSize, (pageIndex + 1) * pageSize),
-  [allRows, pageIndex, pageSize],
-)
-```
-
-Correct:
-
-```ts
-const table = useTable({
-  features: tableFeatures({ rowPaginationFeature }),
-  rowModels: { paginatedRowModel: createPaginatedRowModel() },
-  columns,
-  data,
-})
-// table.nextPage(), table.setPageIndex(...), table.getRowModel().rows
-```
+Correct: `const options = { onPaginationChange: setPagination, autoResetPageIndex: false }`
 
-The built-in APIs honor `autoResetPageIndex`, `paginateExpandedRows`, and reset interactions across other features.
+Client data and processing changes may reset page index; configure the policy when product state must retain it.
 
-Source: maintainer interview (Phase 4, 2026-05-17)
+Source: `docs/framework/react/guide/pagination.md#auto-reset-page-index`
 
-## See also
+## API Discovery
 
-- `tanstack-table/state-management` — `manualPagination` + `autoResetAll`
-- `tanstack-table/row-expanding` — `paginateExpandedRows` interaction
-- `tanstack-table/row-selection` — "select all" pitfalls under server pagination
+Inspect `node_modules/@tanstack/table-core/src/features/row-pagination/` for reset rules, count calculation, and navigation APIs.