TanStack Table v8 서버 사이드 데이터 그리드 — manualPagination·manualSorting·manualFiltering로 페이지네이션·정렬·필터를 서버에 위임하는 패턴

[사용자 인터랙션]
  → 컬럼 헤더 클릭(정렬) / 필터 입력 / 페이지 이동
  → onSortingChange / onColumnFiltersChange / onPaginationChange 호출
  → 외부 state 업데이트
  → queryKey 변경 감지
  → TanStack Query가 queryFn 재실행
  → 서버에서 새 데이터 수신
  → 테이블 리렌더링

import { useState } from 'react';
import { useQuery, keepPreviousData } from '@tanstack/react-query';
import {
  useReactTable,
  getCoreRowModel,
  flexRender,
  type SortingState,
  type ColumnFiltersState,
  type PaginationState,
} from '@tanstack/react-table';
 
export function UserTable() {
  const [pagination, setPagination] = useState<PaginationState>({
    pageIndex: 0,
    pageSize: 20,
  });
  const [sorting, setSorting] = useState<SortingState>([]);
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
 
  // 세 상태가 모두 queryKey에 포함 → 어느 하나라도 바뀌면 자동 재조회
  const { data, isLoading } = useQuery({
    queryKey: ['users', pagination, sorting, columnFilters],
    queryFn: () => fetchUsers({ pagination, sorting, columnFilters }),
    placeholderData: keepPreviousData,
  });
 
  const table = useReactTable({
    data: data?.rows ?? [],
    columns,
    getCoreRowModel: getCoreRowModel(),
    manualPagination: true,
    manualSorting: true,
    manualFiltering: true,
    enableMultiSort: false,     // 멀티 소팅 미지원 시 명시 권장
    rowCount: data?.totalCount, // v8.13.0+: pageCount 자동 계산
    state: { pagination, sorting, columnFilters },
    onPaginationChange: setPagination,
    onSortingChange: (updater) => {
      setSorting(updater);
      setPagination((prev) => ({ ...prev, pageIndex: 0 }));
    },
    onColumnFiltersChange: (updater) => {
      setColumnFilters(updater);
      setPagination((prev) => ({ ...prev, pageIndex: 0 }));
    },
  });
 
  return (
    <table>
      <thead>
        {table.getHeaderGroups().map((headerGroup) => (
          <tr key={headerGroup.id}>
            {headerGroup.headers.map((header) => (
              <th
                key={header.id}
                onClick={header.column.getToggleSortingHandler()}
                style={{ cursor: header.column.getCanSort() ? 'pointer' : 'default' }}
              >
                {flexRender(header.column.columnDef.header, header.getContext())}
                {header.column.getIsSorted() === 'asc' ? ' ↑' : ''}
                {header.column.getIsSorted() === 'desc' ? ' ↓' : ''}
              </th>
            ))}
          </tr>
        ))}
      </thead>
      <tbody>
        {isLoading ? (
          <tr><td colSpan={columns.length}>로딩 중...</td></tr>
        ) : (
          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>
  );
}

// 단일 정렬 파라미터 변환 (enableMultiSort: false 시)
// 범용 형식: ?sortBy=name&sortOrder=asc
// Spring Boot Pageable 형식: ?sort=name,asc (백엔드 스타일에 맞게 조정)
const sortBy = sorting[0]?.id;
const sortOrder = sorting[0]?.desc ? 'desc' : 'asc';
 
// columnFilters 배열 → API 파라미터 객체로 변환
const filterParams = columnFilters.reduce((acc, filter) => {
  // 주의: filter.value가 배열([Date, Date] 등 범위 필터)인 경우
  // URLSearchParams에 직접 넣으면 '[object Object]'로 직렬화됩니다
  // 복합 값은 JSON.stringify 또는 커스텀 직렬화가 필요합니다
  acc[filter.id] = filter.value as string;
  return acc;
}, {} as Record<string, string>);
 
const fetchUsers = async ({
  pagination,
  sorting,
  columnFilters,
}: {
  pagination: PaginationState;
  sorting: SortingState;
  columnFilters: ColumnFiltersState;
}) => {
  const params = new URLSearchParams({
    page: String(pagination.pageIndex),
    size: String(pagination.pageSize),
    ...(sortBy && { sortBy, sortOrder }),
    ...filterParams,
  });
  const res = await fetch(`/api/users?${params}`);
  return res.json() as Promise<{ rows: User[]; totalCount: number }>;
};

function useDebounce<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
  return debounced;
}
 
// 컴포넌트 내부
const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
 
// UI에는 즉각 반응하되, 서버 요청은 300ms 후에만 발생
const debouncedFilters = useDebounce(columnFilters, 300);
 
const { data } = useQuery({
  queryKey: ['users', pagination, sorting, debouncedFilters],
  queryFn: () => fetchUsers({
    pagination,
    sorting,
    columnFilters: debouncedFilters, // 디바운스된 값만 서버로
  }),
  placeholderData: keepPreviousData, // 재조회 중 이전 데이터 유지
});
 
const table = useReactTable({
  data: data?.rows ?? [],
  state: {
    pagination,
    sorting,
    columnFilters, // UI 상태는 즉각 반영
  },
  onColumnFiltersChange: (updater) => {
    setColumnFilters(updater);
    setPagination((prev) => ({ ...prev, pageIndex: 0 }));
  },
  // ...나머지 옵션
});

import { useTableSearchParams } from 'tanstack-table-search-params';
import { useRouter, usePathname, useSearchParams } from 'next/navigation';
 
export function UserTable() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();
 
  // URL 파라미터와 양방향 동기화되는 상태 + 핸들러를 한 번에 받아옵니다
  const stateAndOnChanges = useTableSearchParams({
    push: (url) => router.push(url),
    pathname,
    searchParams,
  });
 
  const { data } = useQuery({
    queryKey: ['users', stateAndOnChanges.state],
    queryFn: () => fetchUsers(stateAndOnChanges.state),
    placeholderData: keepPreviousData,
  });
 
  const table = useReactTable({
    data: data?.rows ?? [],
    columns,
    getCoreRowModel: getCoreRowModel(),
    manualPagination: true,
    manualFiltering: true,
    manualSorting: true,
    rowCount: data?.totalCount,
    ...stateAndOnChanges, // state + onPaginationChange + onSortingChange + onColumnFiltersChange 주입
  });
 
  // 렌더링은 예시 1과 동일
}