Improving Row Pinning behavior with manual Server-Side pagination

[lflangis]

Hi,

The current row pinning feature works great if used with a client-side pagination but it seems quite limited when using a server-side pagination.

e.g.

1. The user is at the first page and pin the third rows. Tanstack table's rowPinning state will the keep the index of that row. The index is 2.
2. The user go to the next page of the table. A new call is make to the server and new data are loaded.
3. A row is still pinned but it does not contains the data that have been previously pinned. It's now containing the data of new call to the server at the same index.

Proposal
In a very naive way, I think tanstack should keep track of the whole row's data instead of just the index. I think, it could be flexible to save pinned row in local storage and ensure the correct data are displayed.

Thanks

[amasen02]

The behavior you observed happens because of two factors:

1. Default Row IDs are indices: Without a custom getRowId, TanStack Table keys rows by their array index ("0", "1", "2"). When page 2 loads, index "2" resolves to the 3rd row of page 2 rather than your original row.
2. Server-side data replaces the array: TanStack Table is a headless state manager—it can only render rows whose data exists in the current data array. When page 2 loads, the server response omitted page 1's pinned item.

Here is how to implement cross-page server-side row pinning reliably:

---

Step 1: Supply getRowId with a Unique Identifier

Tell TanStack Table to track rows by their unique ID (e.g., database primary key) rather than array indices:

const table = useReactTable({
  data: tableData,
  columns,
  getRowId: (row) => row.id, // Stores ['user_42'] in rowPinning instead of ['2']
  state: {
    rowPinning,
  },
  onRowPinningChange: setRowPinning,
  // ...
});

Now rowPinning.top stores stable string IDs like ['id_101'].

---

Step 2: Retain Pinned Row Data Across Page Fetches

Because the server only sends the active page, maintain a client-side cache of pinned row data and prepend any pinned items that are not present in the current page payload:

import { useState, useMemo } from 'react';
import { RowPinningState } from '@tanstack/react-table';

export function useServerRowPinning<T extends { id: string }>(serverRows: T[]) {
  const [rowPinning, setRowPinning] = useState<RowPinningState>({ top: [], bottom: [] });
  const [pinnedDataCache, setPinnedDataCache] = useState<Map<string, T>>(new Map());

  // Cache pinned row data when pinned
  const onRowPinningChange = (updater: any) => {
    setRowPinning((prev) => {
      const next: RowPinningState = typeof updater === 'function' ? updater(prev) : updater;
      
      // Update our data cache with active server rows
      setPinnedDataCache((cache) => {
        const nextCache = new Map(cache);
        const allPinnedIds = new Set([...(next.top ?? []), ...(next.bottom ?? [])]);

        // Add newly pinned items from current page
        serverRows.forEach((row) => {
          if (allPinnedIds.has(row.id)) {
            nextCache.set(row.id, row);
          }
        });

        // Prune unpinned items
        for (const id of nextCache.keys()) {
          if (!allPinnedIds.has(id)) {
            nextCache.delete(id);
          }
        }
        return nextCache;
      });

      return next;
    });
  };

  // Merge cached pinned rows into current page data so TanStack Table can render them
  const mergedData = useMemo(() => {
    const currentPageIds = new Set(serverRows.map((r) => r.id));
    const offPagePinnedRows: T[] = [];

    pinnedDataCache.forEach((row, id) => {
      if (!currentPageIds.has(id)) {
        offPagePinnedRows.push(row);
      }
    });

    return [...offPagePinnedRows, ...serverRows];
  }, [serverRows, pinnedDataCache]);

  return {
    mergedData,
    rowPinning,
    onRowPinningChange,
  };
}

Why this solves it:

1. getRowId: (row) => row.id prevents index collisions when switching pages.
2. mergedData ensures the pinned records remain in memory for TanStack Table's row model to position at the top/bottom while navigating through subsequent server-side pages.