@tanstack/react-table 개념과 사용법 완전 정리

 

 React로 테이블을 만들다 보면 정렬, 필터, 페이지네이션 같은 기능이 필요해지는 순간이 온다.

이걸 일일이 구현하려면 정말 많은 상태 관리와 복잡한 조건 처리가 필요한데

 

그래서 등장한 라이브러리가 바로 @tanstack/react-table 이다.

 

 

@tanstack/react-table이란?

@tanstack/react-table은 UI 없는 테이블 로직 라이브러리이다.

 

즉, 테이블을 보여주는 UI는 직접 만들고,

정렬, 필터, 페이지네이션, 트리 구조, 상태 계산은 라이브러리(react-table) 처리해주는 구조이다.

 

 

📌 설치하기

npm install @tanstack/react-table

Tailwind 기반 UI 만들 경우

npx shadcn-ui@latest add table

 

 

---

 

💡핵심 개념

개념	설명
Column Definitions	어떤 컬럼이 있고, 어떤 데이터를 보여줄지 정의
useReactTable	테이블의 상태와 기능을 관리하는 훅
Table Instace	정렬, 필터링 등 테이블 관련 상태와 메서드를 포함
Render functions	직접 <table>, <tr>,<td>  등을 구성해야 함

 

 

📝 기본 사용 흐름

src/
└── components/
    └── FeatureTable/
        ├── FeatureTable.tsx        ✅ 1. 테이블 컴포넌트 (렌더링)
        ├── columns.ts              ✅ 2. 컬럼 정의
        ├── data.ts                 ✅ 3. 테스트용/더미 데이터
        ├── types.ts                ✅ 4. 데이터 타입 정의 (optional)

1. 데이터 정의

const data = [
  { id: 1, name: "김철수", email: "chulsoo@example.com" },
  { id: 2, name: "박영희", email: "younghee@example.com" },
];

 

2. 컬럼 정의

컬럼 구성은 ColumnDef<T>[]형식으로 정의한다. 

import { ColumnDef } from "@tanstack/react-table";

const columns: ColumnDef<User>[] = [
  {
    accessorKey: "name",
    header: "이름",
  },
  {
    accessorKey: "email",
    header: "이메일",
  },
];

 

 

3. 테이블 객체 생성

React Table의 핵심 훅으로, 테이블 상태와 렌더링 도구를 관리한다.

import {
  useReactTable,
  getCoreRowModel,
} from "@tanstack/react-table";

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
});

 

4. 렌더링

<table>
  <thead>
    {table.getHeaderGroups().map(headerGroup => (
      <tr key={headerGroup.id}>
        {headerGroup.headers.map(header => (
          <th key={header.id}>
            {header.column.columnDef.header}
          </th>
        ))}
      </tr>
    ))}
  </thead>
  <tbody>
    {table.getRowModel().rows.map(row => (
      <tr key={row.id}>
        {row.getVisibleCells().map(cell => (
          <td key={cell.id}>
            {cell.getValue()}
          </td>
        ))}
      </tr>
    ))}
  </tbody>
</table>

 

 

요약

개념	설명
data	테이블에 보여줄 데이터 배열
columns	각 컬럼 정의 (제목, accessorKey 등)
useReactTable()	테이블 로직 생성 함수
getCoreRowModel()	기본 행 계산기
getRowModel()	최종적으로 렌더링할 행 리스트 반환