TanStack Table + TanStack Virtual + React Query로 50,000행 × 200열 데이터 그리드를 60FPS로 가상화하기

전체 데이터: 50,000행
      ↓
React Query: 서버에서 50개씩 청크로 페칭 → 페이지 배열로 관리
      ↓
TanStack Table: flatData를 받아 정렬·필터 적용 → row model 구성
      ↓
TanStack Virtual: 현재 보이는 행 인덱스 17개만 추출
      ↓
실제 DOM: <tr> 17개만 존재

// types.ts
type User = {
  id: string
  name: string
  email: string
  department: string
  joinedAt: string
}
 
type FetchUsersResponse = {
  rows: User[]
  nextCursor: number | null
  totalCount: number
}
 
async function fetchUsers({
  page,
  limit,
}: {
  page: number
  limit: number
}): Promise<FetchUsersResponse> {
  const res = await fetch(`/api/users?page=${page}&limit=${limit}`)
  if (!res.ok) throw new Error('fetch failed')
  return res.json()
}

// VirtualizedTable.tsx
import {
  useInfiniteQuery,
} from '@tanstack/react-query'
import {
  useReactTable,
  getCoreRowModel,
  flexRender,
  type ColumnDef,
} from '@tanstack/react-table'
import { useVirtualizer } from '@tanstack/react-virtual'
import { useRef, useMemo, useEffect } from 'react'
 
const FETCH_SIZE = 50
 
const columns: ColumnDef<User>[] = [
  { accessorKey: 'name', header: '이름', size: 150 },
  { accessorKey: 'email', header: '이메일', size: 200 },
  { accessorKey: 'department', header: '부서', size: 120 },
  { accessorKey: 'joinedAt', header: '입사일', size: 120 },
]
 
export function VirtualizedTable() {
  const tableContainerRef = useRef<HTMLDivElement>(null)
 
  // 1. React Query: 서버에서 페이지 단위로 데이터 페칭
  const { data, fetchNextPage, hasNextPage, isFetching } =
    useInfiniteQuery({
      queryKey: ['users'],
      queryFn: ({ pageParam }) =>
        fetchUsers({ page: pageParam as number, limit: FETCH_SIZE }),
      getNextPageParam: (lastPage) => lastPage.nextCursor,
      initialPageParam: 0,
    })
 
  // 2. 페이지 배열을 flat한 단일 배열로 변환
  const flatData = useMemo(
    () => data?.pages.flatMap((page) => page.rows) ?? [],
    [data]
  )
  const totalCount = data?.pages[0]?.totalCount ?? 0
 
  // 3. TanStack Table: row model 구성
  const table = useReactTable({
    data: flatData,
    columns,
    getCoreRowModel: getCoreRowModel(),
    // 서버사이드 데이터를 쓸 때 이 두 옵션을 빠뜨리면 페이지 계산이 틀어집니다
    manualPagination: true,
    rowCount: totalCount,
  })
 
  const { rows } = table.getRowModel()
 
  // 4. TanStack Virtual: 현재 보이는 행만 렌더링
  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => tableContainerRef.current,
    estimateSize: () => 48,
    overscan: 10,
  })
 
  const virtualRows = rowVirtualizer.getVirtualItems()
 
  // 5. 스크롤 끝 감지 → 다음 페이지 자동 페칭
  useEffect(() => {
    const lastItem = virtualRows.at(-1)
    if (
      lastItem &&
      lastItem.index >= flatData.length - 1 &&
      hasNextPage &&
      !isFetching
    ) {
      fetchNextPage()
    }
  }, [virtualRows, flatData.length, hasNextPage, isFetching, fetchNextPage])
 
  const totalSize = rowVirtualizer.getTotalSize()
 
  return (
    <div
      ref={tableContainerRef}
      style={{ height: '600px', overflow: 'auto', position: 'relative' }}
    >
      <table style={{ display: 'grid' }}>
        <thead>
          {table.getHeaderGroups().map((headerGroup) => (
            <tr key={headerGroup.id} style={{ display: 'flex' }}>
              {headerGroup.headers.map((header) => (
                <th key={header.id} style={{ width: header.getSize() }}>
                  {flexRender(
                    header.column.columnDef.header,
                    header.getContext()
                  )}
                </th>
              ))}
            </tr>
          ))}
        </thead>
        <tbody
          style={{ height: `${totalSize}px`, position: 'relative' }}
        >
          {virtualRows.map((virtualRow) => {
            const row = rows[virtualRow.index]
            return (
              <tr
                key={row.id}
                style={{
                  position: 'absolute',
                  transform: `translateY(${virtualRow.start}px)`,
                  display: 'flex',
                  width: '100%',
                }}
              >
                {row.getVisibleCells().map((cell) => (
                  <td
                    key={cell.id}
                    style={{ width: cell.column.getSize() }}
                  >
                    {flexRender(
                      cell.column.columnDef.cell,
                      cell.getContext()
                    )}
                  </td>
                ))}
              </tr>
            )
          })}
        </tbody>
      </table>
      {isFetching && <div>Loading more...</div>}
    </div>
  )
}

// BidirectionalVirtualizedTable.tsx
// React Query + flatData 부분은 예시 1과 동일 — 아래는 table/virtualizer 이후만 표시
 
import {
  useReactTable,
  getCoreRowModel,
  flexRender,
  type ColumnDef,
  type Header,
} from '@tanstack/react-table'
import { useVirtualizer } from '@tanstack/react-virtual'
import { useRef, useMemo } from 'react'
 
export function BidirectionalVirtualizedTable({
  flatData,        // 예시 1의 flatData와 동일한 구조
  totalCount,
}: {
  flatData: User[]
  totalCount: number
}) {
  const tableContainerRef = useRef<HTMLDivElement>(null)
 
  const table = useReactTable({
    data: flatData,
    columns, // 예: 200개 컬럼 (ColumnDef<User>[] 타입)
    getCoreRowModel: getCoreRowModel(),
    manualPagination: true,
    rowCount: totalCount,
    defaultColumn: { size: 150 },
  })
 
  const { rows } = table.getRowModel()
  const visibleColumns = table.getVisibleLeafColumns()
 
  // 헤더를 컬럼 ID로 매핑 — 인덱스 접근 대신 ID 기반 lookup으로 안전하게
  const headerByColumnId = useMemo(() => {
    const leafHeaders =
      table.getHeaderGroups().at(-1)?.headers ?? []
    return new Map<string, Header<User, unknown>>(
      leafHeaders.map((h) => [h.column.id, h])
    )
  }, [table])
 
  // 행 virtualizer (수직)
  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => tableContainerRef.current,
    estimateSize: () => 35,
    overscan: 5,
  })
 
  // 열 virtualizer (수평)
  const columnVirtualizer = useVirtualizer({
    horizontal: true,
    count: visibleColumns.length,
    getScrollElement: () => tableContainerRef.current,
    estimateSize: (index) => visibleColumns[index].getSize(),
    overscan: 3,
  })
 
  const virtualRows = rowVirtualizer.getVirtualItems()
  const virtualColumns = columnVirtualizer.getVirtualItems()
 
  const totalRowHeight = rowVirtualizer.getTotalSize()
  const totalColWidth = columnVirtualizer.getTotalSize()
 
  return (
    <div
      ref={tableContainerRef}
      style={{ height: '600px', width: '100%', overflow: 'auto' }}
    >
      <div
        style={{
          height: `${totalRowHeight}px`,
          width: `${totalColWidth}px`,
          position: 'relative',
        }}
      >
        {/* 헤더 — position: sticky로 상단 고정 */}
        <div
          style={{
            position: 'sticky',
            top: 0,
            zIndex: 1,
            background: 'white',
          }}
        >
          {virtualColumns.map((virtualColumn) => {
            const col = visibleColumns[virtualColumn.index]
            const header = headerByColumnId.get(col.id)
            if (!header) return null
            return (
              <div
                key={virtualColumn.key}
                style={{
                  position: 'absolute',
                  left: virtualColumn.start,
                  width: virtualColumn.size,
                  height: 35,
                }}
              >
                {flexRender(
                  header.column.columnDef.header,
                  header.getContext()
                )}
              </div>
            )
          })}
        </div>
 
        {/* 바디 — 행·열 교차점만 렌더링 */}
        {virtualRows.map((virtualRow) => {
          const row = rows[virtualRow.index]
          const visibleCells = row.getVisibleCells()
          return virtualColumns.map((virtualColumn) => {
            const cell = visibleCells[virtualColumn.index]
            return (
              <div
                key={`${virtualRow.index}-${virtualColumn.index}`}
                style={{
                  position: 'absolute',
                  top: virtualRow.start + 35, // 헤더 높이 오프셋
                  left: virtualColumn.start,
                  width: virtualColumn.size,
                  height: virtualRow.size,
                }}
              >
                {flexRender(
                  cell.column.columnDef.cell,
                  cell.getContext()
                )}
              </div>
            )
          })
        })}
      </div>
    </div>
  )
}

[스크롤 컨테이너: overflow: auto, position: relative]
  └─ [전체 크기 div: width/height 총합, position: relative]
       ├─ [Sticky 헤더: position: sticky, top: 0, zIndex: 2]
       │    └─ [가상 열 헤더들: position: absolute, left: ...]
       │         ※ 이 안에 transform이 있어서는 안 됩니다
       └─ [바디: position: relative, top: 헤더높이]
            └─ [가상 셀들: position: absolute, top/left: ...]

// 예시 2의 BidirectionalVirtualizedTable에서 고정 열 처리 추가
 
// 컬럼 정의에 sticky 메타 추가
const columns: ColumnDef<User>[] = [
  {
    id: 'name',
    header: '이름',
    accessorKey: 'name',
    size: 200,
    meta: { sticky: true },
  },
  // ...나머지 컬럼들
]
 
// 렌더링 시 — 예시 2의 바디 렌더링 부분을 아래로 교체
{virtualRows.map((virtualRow) => {
  const row = rows[virtualRow.index]
  const visibleCells = row.getVisibleCells()
  return virtualColumns.map((virtualColumn) => {
    const isSticky = virtualColumn.index === 0
    const cell = visibleCells[virtualColumn.index]
    return (
      <div
        key={`${virtualRow.index}-${virtualColumn.index}`}
        style={{
          // sticky 열은 absolute 대신 sticky 사용
          position: isSticky ? 'sticky' : 'absolute',
          top: isSticky
            ? virtualRow.start + 35
            : virtualRow.start + 35,
          left: isSticky ? 0 : virtualColumn.start,
          zIndex: isSticky ? 2 : 0,
          width: virtualColumn.size,
          height: virtualRow.size,
          background: isSticky ? 'white' : 'transparent',
          // ※ transform을 sticky 요소에 직접 적용하지 않습니다
        }}
      >
        {flexRender(cell.column.columnDef.cell, cell.getContext())}
      </div>
    )
  })
})}