TanStack Table 필터·정렬을 URL search params에 동기화하기 — URL 상태 동기화 실전 패턴 (URL state sync)

// @tanstack/zod-adapter v1 기준 (버전에 따라 패키지명이 다를 수 있습니다)
import { z } from 'zod'
import { createFileRoute } from '@tanstack/react-router'
import { zodValidator, fallback } from '@tanstack/zod-adapter'
 
const tableSearchSchema = z.object({
  columnFilters: z
    .array(z.object({ id: z.string(), value: z.unknown() }))
    .default([]),
  sorting: z
    .array(z.object({ id: z.string(), desc: z.boolean() }))
    .default([]),
  pageIndex: fallback(z.number().int().nonnegative(), 0),
  pageSize: fallback(z.number().int().positive(), 20),
})
 
export const Route = createFileRoute('/products')({
  validateSearch: zodValidator(tableSearchSchema),
})

import {
  useReactTable,
  getCoreRowModel,
  functionalUpdate,
} from '@tanstack/react-table'
import { useNavigate } from '@tanstack/react-router'
 
// on*Change 핸들러 공통 패턴
onColumnFiltersChange: (updater) => {
  const next = functionalUpdate(updater, columnFilters)
  navigate({
    search: (prev) => ({ ...prev, columnFilters: next, pageIndex: 0 }),
    replace: true,
  })
},

import { useQuery } from '@tanstack/react-query'
import { useNavigate } from '@tanstack/react-router'
import {
  useReactTable,
  getCoreRowModel,
  functionalUpdate,
  type ColumnDef,
} from '@tanstack/react-table'
 
// 데이터 fetching 로직을 커스텀 훅으로 분리
function useProductsQuery() {
  const { columnFilters, sorting, pageIndex, pageSize } = Route.useSearch()
 
  return useQuery({
    // queryKey에 search params 포함 — URL 변경 시 자동 리페치됩니다
    queryKey: ['products', { columnFilters, sorting, pageIndex, pageSize }],
    queryFn: () =>
      fetchProducts({
        filters: columnFilters,
        sorting,
        page: pageIndex,
        limit: pageSize,
      }),
    placeholderData: (prev) => prev, // 페이지 전환 시 빈 화면 대신 이전 데이터 유지
  })
}
 
interface Product {
  id: string
  name: string
  status: string
}
 
const columns: ColumnDef<Product>[] = [
  // ... 컬럼 정의
]
 
function ProductTable() {
  const { data, isLoading, isFetching } = useProductsQuery()
  const { columnFilters, sorting, pageIndex, pageSize } = Route.useSearch()
  const navigate = useNavigate({ from: Route.fullPath })
 
  const table = useReactTable({
    data: data?.items ?? [],
    columns,
    rowCount: data?.total ?? 0,
    getCoreRowModel: getCoreRowModel(),
    state: {
      columnFilters,
      sorting,
      pagination: { pageIndex, pageSize },
    },
    manualFiltering: true,
    manualSorting: true,
    manualPagination: true,
    onColumnFiltersChange: (updater) => {
      const next = functionalUpdate(updater, columnFilters)
      navigate({
        search: (prev) => ({ ...prev, columnFilters: next, pageIndex: 0 }),
        replace: true,
      })
    },
    onSortingChange: (updater) => {
      const next = functionalUpdate(updater, sorting)
      navigate({
        search: (prev) => ({ ...prev, sorting: next }),
        replace: true,
      })
    },
    onPaginationChange: (updater) => {
      const next = functionalUpdate(updater, { pageIndex, pageSize })
      navigate({
        search: (prev) => ({
          ...prev,
          pageIndex: next.pageIndex,
          pageSize: next.pageSize,
        }),
        replace: true,
      })
    },
  })
 
  return (
    <div>
      {isFetching && <div className="loading-indicator">로딩 중...</div>}
      {/* 테이블 렌더링 */}
    </div>
  )
}

import { useState, useEffect } from 'react'
import { useDebounce } from 'use-debounce' // 또는 직접 구현 가능
 
function DebouncedFilterInput({
  columnId,
  placeholder,
}: {
  columnId: string
  placeholder: string
}) {
  const { columnFilters } = Route.useSearch()
  const navigate = useNavigate({ from: Route.fullPath })
 
  // 현재 URL에서 이 컬럼의 필터 값 읽기
  const currentValue =
    (columnFilters.find((f) => f.id === columnId)?.value as string) ?? ''
 
  // 로컬 state로 입력값 관리 (타이핑 즉시 반응)
  const [inputValue, setInputValue] = useState(currentValue)
  const [debouncedValue] = useDebounce(inputValue, 300)
 
  // 디바운스된 값이 바뀔 때만 URL 업데이트
  useEffect(() => {
    if (debouncedValue === currentValue) return
 
    navigate({
      search: (prev) => ({
        ...prev,
        columnFilters: debouncedValue
          ? [
              ...prev.columnFilters.filter((f) => f.id !== columnId),
              { id: columnId, value: debouncedValue },
            ]
          : prev.columnFilters.filter((f) => f.id !== columnId),
        pageIndex: 0,
      }),
      replace: true,
    })
  }, [debouncedValue, currentValue, navigate, columnId])
  //  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  //  exhaustive-deps 충족 + debouncedValue === currentValue 가드로 루프 방지
 
  return (
    <input
      value={inputValue}
      onChange={(e) => setInputValue(e.target.value)}
      placeholder={placeholder}
    />
  )
}