Tanstack Table 쓰기 전에 공식문서 읽어보기(번역과 함께)

들어가며

최근 취업을 준비하면서, 친구들과 함께 면접 질문을 아카이빙하고 관리할 수 있는 토이 프로젝트를 진행하고 있습니다.
면접 준비 과정에서 자주 등장하는 질문들을 정리하고, 카테고리별로 분류하거나 검색할 수 있는 기능이 있으면 좋겠다는 아이디어에서 출발한 프로젝트입니다. 이 과정에서 질문 데이터를 테이블 형태로 보여줄 필요가 있었고, 어떤 테이블 라이브러리를 사용할지 고민하던 중 TanStack Table을 선택하게 되었습니다.

기존에도 프로젝트에서 Shadcn UI를 사용하고 있었기 때문에, 같은 Headless UI 접근 방식을 유지하는 것이 좋겠다는 결론을 팀원들과 함께 내린 점도 선택에 큰 영향을 주었습니다.
또, 향후 데이터 패칭이나 무한 스크롤 기능을 직접 구현해보고, 이후에 TanStack Query를 접목시켜보면서 그 필요성과 효용성도 자연스럽게 체감해볼 수 있겠다는 기대도 있었습니다.

그래서 오늘 글에서는 본격적으로 기능을 구현하기에 앞서, TanStack Table 공식 문서의 최신 내용을 직접 번역하고 정리한 내용을 공유해보려고 합니다. 공식 문서가 영어로 되어 있다 보니, 번역 과정을 통해 개념을 더 명확히 이해할 수 있었고, 이 과정 자체도 큰 도움이 되었습니다. 번역 하는 과정에서 GPT와 함께 하다 보니 오류가 있을 수 있어서 혹시 틀린 부분이 있다면 편하게 코멘트 부탁드립니다. 

Introduction

Introduction | TanStack Table Docs

Headless UI 란 무엇일까?

Headless UI란 UI 요소와 상호작용을 위한 로직, 상태 관리, 처리 과정, 그리고 API는 제공하지만, 마크업(HTML 구조), 스타일(CSS), 미리 구현된 UI 구성 요소는 제공하지 않는 라이브러리나 유틸리티를 가리키는 용어입니다.

복잡한 사용자 인터페이스(UI)를 구축할 때 가장 어려운 부분은 보통 상태 관리, 이벤트 처리, 부수 효과(side-effect), 데이터 계산 및 관리와 같은 영역입니다.

Headless UI는 이러한 요소들을 마크업, 스타일, 그리고 구현 세부 사항으로부터 분리해 줌으로써, 로직과 컴포넌트를 더 모듈화하고 재사용 가능하게 만들어줍니다.

UI를 구축하는 일은 매우 브랜드 지향적이고 사용자 맞춤적인 작업입니다. 심지어 디자인 시스템을 선택하거나 디자인 명세를 따르는 경우에도 마찬가지입니다. 이러한 맞춤형 경험을 지원하려면, 컴포넌트 기반 UI 라이브러리는 마크업과 스타일 커스터마이징을 위한 방대한(끝이 없어 보이는) API 제공 범위를 감당해야 합니다. 반면, Headless UI 라이브러리는 로직과 UI(보여지는 부분)를 분리함으로써 이러한 부담을 줄여줍니다.

Headless UI 라이브러리를 사용하면, 데이터 처리, 상태 관리, 그리고 비즈니스 로직과 같은 복잡한 작업들을 라이브러리가 대신 처리해줍니다. 그 덕분에 개발자는 구현 방식이나 사용 사례마다 달라지는, 보다 고차원의 의사결정에 집중할 수 있게 됩니다.

컴포넌트 기반 라이브러리 vs Headless 라이브러리

테이블/데이터 그리드 라이브러리 생태계에서는 두 가지 주요 범주가 존재합니다:

• 컴포넌트 기반 테이블 라이브러리
• Headless 테이블 라이브러리

❓ 어떤 테이블 라이브러리를 사용해야 할까요?

각 접근 방식은 미묘한 장단점이 있습니다. 이러한 미묘한 차이를 이해하면, 여러분의 애플리케이션과 팀에 적합한 선택을 할 수 있습니다.

컴포넌트 기반 테이블 라이브러리 (Component-based Table Libraries)

컴포넌트 기반 테이블 라이브러리는 보통 풍부한 기능을 갖춘 '바로 사용할 수 있는' 솔루션과, 스타일/테마가 적용된 완성된 컴포넌트 및 마크업을 제공합니다.

대표적인 예로는 AG Grid가 있습니다.

✅ 장점

• 기본적으로 사용 가능한 마크업과 스타일을 제공합니다.
• 설정이 거의 필요하지 않습니다.
• "그냥 끼워넣는(turn-key)" 경험을 제공합니다.

❌ 단점

• 마크업에 대한 제어가 제한됩니다.
• 스타일 커스터마이징이 보통 테마 기반으로 제한됩니다.
• 번들 크기가 더 큽니다.
• 프레임워크 어댑터 및 플랫폼에 강하게 결합되어 있습니다.

👉 요약

만약 "바로 사용할 수 있는 테이블"이 필요하고, 디자인이나 번들 크기가 중요한 요구사항이 아니라면, 컴포넌트 기반 테이블 라이브러리를 고려하셔도 좋습니다.

AG Grid 외에도 다양한 컴포넌트 기반 테이블 라이브러리들이 존재하지만, 우리는 AG Grid를 테이블 라이브러리 중 최고로 생각하며,저희가 가장 좋아하는 그리드 라이브러리입니다. (다른 친구들에게는 비밀이에요 🤫)

Headless 테이블 라이브러리 (Headless Table Libraries)

Headless 테이블 라이브러리는 보통 함수, 상태(state), 유틸리티, 이벤트 리스너 등을 제공하여, 직접 테이블 마크업을 구성하거나 기존 마크업에 연결할 수 있도록 도와줍니다.

✅ 장점

• 마크업과 스타일을 완전히 제어할 수 있습니다.
• 모든 스타일링 방식(CSS, CSS-in-JS, UI 라이브러리 등)을 지원합니다.
• 번들 크기가 작습니다.
• 이식성이 높아, JavaScript가 실행되는 모든 곳에서 동작합니다.

❌ 단점

• 더 많은 설정이 필요합니다.
• 마크업, 스타일, 테마가 기본으로 제공되지 않습니다.

👉 요약

더 가볍고 유연한 테이블을 원하시거나, 디자인을 직접 완전히 제어하고 싶으시다면, Headless 테이블 라이브러리를 고려하시는 것이 좋습니다. Headless 테이블 라이브러리는 현재 많지 않지만, 우리는 TanStack Table이 그 중 최고이며, 당연히 저희의 최애 라이브러리입니다!

Overview

Overview | TanStack Table Docs

프레임워크 비의존적(Framework Agnostic)

TanStack Table의 핵심은 프레임워크에 의존하지 않는 구조로 되어 있습니다. 즉, 어떤 프레임워크를 사용하든 동일한 API를 사용할 수 있다는 의미입니다. 사용 중인 프레임워크에 따라 TanStack Table 코어와 쉽게 연동할 수 있도록 어댑터(Adapters)가 제공됩니다.

사용 가능한 어댑터 목록은 좌측 메뉴의 “Adapters” 섹션에서 확인하실 수 있습니다.

TypeScript

TanStack Table은 TypeScript로 작성되어 있지만, TypeScript를 사용하는 것은 선택 사항입니다.

다만, 사용하는 것을 적극 권장합니다. 왜냐하면 TypeScript를 통해 코드의 안전성과 자동 완성 기능 등, 개발자와 코드베이스 모두에 뛰어난 이점을 얻을 수 있기 때문입니다. TypeScript를 사용할 경우, 모든 테이블 API와 상태 관련 코드에서 최고 수준의 타입 안정성과 자동 완성 기능을 누릴 수 있습니다.

Headless

앞서 Intro 섹션에서 언급한 것처럼, TanStack Table은 Headless 방식입니다.

즉, DOM 요소를 직접 렌더링하지 않으며, UI/UX 개발자인 여러분이 직접 테이블 마크업과 스타일을 구성해야 합니다. 이러한 구조는 React, Vue, Solid, Svelte, Qwik, Angular, 심지어 React Native와 같은 JS 기반 네이티브 플랫폼에서도 어떤 UI 프레임워크와도 함께 사용할 수 있는 유연한 테이블을 만들 수 있게 해줍니다.

Agnostic(비의존성)의 두 가지 측면

TanStack Table은 Headless 방식이며 순수 JavaScript 코어로 동작하기 때문에, 다음과 같은 측면에서 비의존적입니다:

1. 프레임워크 비의존성React, Vue, Solid, Svelte, Qwik용 어댑터가 기본 제공되며, 필요시 직접 어댑터를 만들 수도 있습니다.
2. 어떤 JavaScript 프레임워크(또는 라이브러리)와도 사용할 수 있습니다.
3. CSS / 컴포넌트 라이브러리 비의존성TanStack Table은 마크업이나 스타일을 전혀 렌더링하지 않으므로, Tailwind, Shadcn, Material UI, Bootstrap, 또는 여러분만의 디자인 시스템 등
4. 무엇이든 직접 가져와 사용하실 수 있습니다!
5. 원하는 스타일링 방식이나 컴포넌트 라이브러리와 함께 자유롭게 사용할 수 있습니다.

핵심 객체 및 타입(Core Objects and Types)

TanStack Table의 코어는 아래와 같은 추상화 개념들을 사용합니다.

이들은 어댑터를 통해 외부로 노출되어 사용됩니다:

• Data: 테이블에 제공되는 핵심 데이터 배열
• Column Defs: 각 컬럼을 구성하는 설정 객체 (데이터 모델, 렌더링 템플릿 등 포함)
• Table Instance: 테이블의 전체 상태와 API를 담고 있는 중심 객체
• Row Models: 기능에 따라 데이터 배열을 가공해 만든 행(row) 구조
• Rows: 각각의 데이터 행에 해당하며, 행 전용 API를 포함합니다
• Cells: 행과 열의 교차점에 해당하며, 셀 전용 API를 포함합니다
• Header Groups: 중첩된 헤더 구조를 슬라이스 형태로 나타낸 그룹
• Headers: 각 컬럼 정의로부터 파생되거나 직접 연결된 헤더 객체
• Columns: 컬럼 정의를 반영한 컬럼 객체로, 컬럼 전용 API를 포함합니다

기능 (Features)

TanStack Table은 거의 상상할 수 있는 모든 형태의 테이블을 만들 수 있도록 도와줍니다.

다음과 같은 기능들을 위한 내장 상태 및 API를 제공합니다:

• Column Faceting: 특정 컬럼의 유일한 값 목록 또는 최소/최대 값을 추출
• Column Filtering: 컬럼에 대한 검색값으로 행 필터링
• Column Grouping: 컬럼을 그룹화하고, 집계 연산 등을 수행
• Column Ordering: 컬럼 순서를 동적으로 변경
• Column Pinning: 컬럼을 테이블의 좌/우측에 고정
• Column Sizing: 컬럼 크기를 동적으로 조절 (드래그 핸들)
• Column Visibility: 컬럼 숨기기/표시하기
• Global Faceting: 전체 테이블의 유일한 값 목록/최소·최대값
• Global Filtering: 전체 테이블에 대해 검색 기반 필터링
• Row Expanding: 행 확장/축소 (서브 행)
• Row Pagination: 행 페이지네이션
• Row Pinning: 행을 테이블 상단 또는 하단에 고정
• Row Selection: 행 선택/해제 (체크박스 등)
• Row Sorting: 컬럼 값을 기준으로 행 정렬

이 외에도 TanStack Table로 구축 가능한 기능은 훨씬 더 많습니다. Virtualization(가상 스크롤링)과 같이 기본 탑재되어 있진 않지만,다른 라이브러리(TanStack Virtual 등)를 함께 사용하여 확장할 수 있는 기능도 포함됩니다.

또한, Custom Features(플러그인)도 지원합니다. 이 기능을 통해, 테이블 인스턴스에 사용자 정의 로직을 통합된 방식으로 추가할 수 있습니다. 물론, 필요하다면 직접 상태(state)와 훅(hook)을 만들어 자체적인 기능을 테이블에 추가하는 것도 가능합니다.

TanStack Table의 코어 기능들은 성능(performance)과 개발자 경험(DX)에 초점을 맞춘 단단한 기반을 제공합니다.

Installation

저희는 리액트로 프로젝트를 진행 하고 있어서 리액트 버전 테이블로 다운로드를 받아줘야 되서 아래 지시사항에 맞춰서 설치를 완료했습니다. 

React Table

npm install @tanstack/react-table

//The @tanstack/react-table package works with React 16.8, React 17, React 18, and React 19.