Data Table

Data Table (데이터 테이블)

TanStack Table 기반의 강력한 테이블 및 데이터그리드 컴포넌트예요. 복잡한 데이터 테이블을 처음부터 직접 만들어 보고 싶을 때 사용해요.

출처: 문서

본문

소개 (Introduction)

제가 만든 데이터 테이블이나 데이터그리드는 매번 달랐어요. 전부 다르게 동작하고, 저마다 다른 정렬과 필터링 요구 사항이 있으며, 서로 다른 데이터 소스와 함께 동작했어요.

이 모든 변형을 하나의 컴포넌트로 합치는 건 말이 안 돼요. 그렇게 하면 headless UI가 주는 유연성을 잃게 돼요.

그래서 데이터 테이블 컴포넌트 대신, 직접 만드는 방법을 안내해 드리는 게 더 도움이 될 거라고 생각했어요.

기본적인 <Table /> 컴포넌트에서 시작해서 복잡한 데이터 테이블을 처음부터 만들어 볼게요.

팁: 앱의 여러 곳에서 같은 테이블을 쓰고 있다면 언제든 재사용 가능한 컴포넌트로 추출할 수 있어요.

목차 (Table of Contents)

이 가이드에서는 TanStack Table과 <Table /> 컴포넌트로 나만의 커스텀 데이터 테이블을 만드는 방법을 보여줄게요. 다룰 주제는 다음과 같아요.

설치 (Installation)

  1. 프로젝트에 <Table /> 컴포넌트를 추가해요.
npx shadcn@latest add table
  1. tanstack/react-table 의존성을 추가해요.
npm install @tanstack/react-table

사전 준비 (Prerequisites)

최근 결제 내역을 보여주는 테이블을 만들어 볼게요. 데이터는 다음과 같아요.

type Payment = {
  id: string
  amount: number
  status: "pending" | "processing" | "success" | "failed"
  email: string
}

export const payments: Payment[] = [
  {
    id: "728ed52f",
    amount: 100,
    status: "pending",
    email: "[email protected]",
  },
  {
    id: "489e1d42",
    amount: 125,
    status: "processing",
    email: "[email protected]",
  },
  // ...
]

프로젝트 구조 (Project Structure)

다음 파일 구조를 만들어 볼게요.

app
└── payments
    ├── columns.tsx
    ├── data-table.tsx
    └── page.tsx

여기서는 Next.js 예시를 사용하지만 어떤 React 프레임워크에서도 동작해요.

  • columns.tsx (클라이언트 컴포넌트)에 컬럼 정의를 담아요.
  • data-table.tsx (클라이언트 컴포넌트)에 <DataTable /> 컴포넌트를 담아요.
  • page.tsx (서버 컴포넌트)에서 데이터를 가져와 테이블을 렌더링해요.

기본 테이블 (Basic Table)

기본 테이블부터 만들어 볼게요.

컬럼 정의 (Column Definitions)

먼저 컬럼을 정의해요.

"use client"

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

// This type is used to define the shape of our data.
// You can use a Zod schema here if you want.
export type Payment = {
  id: string
  amount: number
  status: "pending" | "processing" | "success" | "failed"
  email: string
}

export const columns: ColumnDef<Payment>[] = [
  {
    accessorKey: "status",
    header: "Status",
  },
  {
    accessorKey: "email",
    header: "Email",
  },
  {
    accessorKey: "amount",
    header: "Amount",
  },
]

참고: 컬럼은 테이블이 어떻게 보일지의 핵심을 정의하는 곳이에요. 표시할 데이터, 포맷, 정렬, 필터링 방식을 정의해요.

<DataTable /> 컴포넌트

다음으로 테이블을 렌더링할 <DataTable /> 컴포넌트를 만들어요.

"use client"

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

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

interface DataTableProps<TData, TValue> {
  columns: ColumnDef<TData, TValue>[]
  data: TData[]
}

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  })

  return (
    <div className="rounded-md border">
      <Table>
        <TableHeader>
          {table.getHeaderGroups().map((headerGroup) => (
            <TableRow key={headerGroup.id}>
              {headerGroup.headers.map((header) => {
                return (
                  <TableHead key={header.id}>
                    {header.isPlaceholder
                      ? null
                      : flexRender(
                          header.column.columnDef.header,
                          header.getContext()
                        )}
                  </TableHead>
                )
              })}
            </TableRow>
          ))}
        </TableHeader>
        <TableBody>
          {table.getRowModel().rows?.length ? (
            table.getRowModel().rows.map((row) => (
              <TableRow
                key={row.id}
                data-state={row.getIsSelected() && "selected"}
              >
                {row.getVisibleCells().map((cell) => (
                  <TableCell key={cell.id}>
                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
                  </TableCell>
                ))}
              </TableRow>
            ))
          ) : (
            <TableRow>
              <TableCell colSpan={columns.length} className="h-24 text-center">
                No results.
              </TableCell>
            </TableRow>
          )}
        </TableBody>
      </Table>
    </div>
  )
}

팁: <DataTable />을 여러 곳에서 사용한다면, 이 컴포넌트를 components/ui/data-table.tsx로 추출해 재사용 가능하게 만들면 돼요.

<DataTable columns={columns} data={data} />

테이블 렌더링하기 (Render the table)

마지막으로 페이지 컴포넌트에서 테이블을 렌더링해요.

import { Payment, columns } from "./columns"
import { DataTable } from "./data-table"

async function getData(): Promise<Payment[]> {
  // Fetch data from your API here.
  return [
    {
      id: "728ed52f",
      amount: 100,
      status: "pending",
      email: "[email protected]",
    },
    // ...
  ]
}

export default async function DemoPage() {
  const data = await getData()

  return (
    <div className="container mx-auto py-10">
      <DataTable columns={columns} data={data} />
    </div>
  )
}

셀 포맷 (Cell Formatting)

amount 셀을 달러 금액으로 포맷해 볼게요. 셀도 오른쪽 정렬할게요.

컬럼 정의 업데이트하기

amount의 header와 cell 정의를 다음과 같이 업데이트해요.

export const columns: ColumnDef<Payment>[] = [
  {
    accessorKey: "amount",
    header: () => <div className="text-right">Amount</div>,
    cell: ({ row }) => {
      const amount = parseFloat(row.getValue("amount"))
      const formatted = new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: "USD",
      }).format(amount)

      return <div className="text-right font-medium">{formatted}</div>
    },
  },
]

같은 방식으로 다른 셀이나 헤더도 포맷할 수 있어요.

행 동작 (Row Actions)

테이블에 행 동작을 추가해 볼게요. 이를 위해 <Dropdown /> 컴포넌트를 사용해요.

컬럼 정의 업데이트하기

새 actions 컬럼을 추가하도록 컬럼 정의를 업데이트해요. actions 셀은 <Dropdown /> 컴포넌트를 반환해요.

"use client"

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

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

export const columns: ColumnDef<Payment>[] = [
  // ...
  {
    id: "actions",
    cell: ({ row }) => {
      const payment = row.original

      return (
        <DropdownMenu>
          <DropdownMenuTrigger asChild>
            <Button variant="ghost" className="h-8 w-8 p-0">
              <span className="sr-only">Open menu</span>
              <MoreHorizontal className="h-4 w-4" />
            </Button>
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end">
            <DropdownMenuLabel>Actions</DropdownMenuLabel>
            <DropdownMenuItem
              onClick={() => navigator.clipboard.writeText(payment.id)}
            >
              Copy payment ID
            </DropdownMenuItem>
            <DropdownMenuSeparator />
            <DropdownMenuItem>View customer</DropdownMenuItem>
            <DropdownMenuItem>View payment details</DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      )
    },
  },
  // ...
]

cell 함수에서 row.original로 행 데이터에 접근할 수 있어요. 이걸로 행에 대한 동작을 처리해요. 예를 들어 id를 사용해 API에 DELETE 요청을 보낼 수 있어요.

페이지네이션 (Pagination)

이제 테이블에 페이지네이션을 추가해 볼게요.

<DataTable> 업데이트하기

import {
  ColumnDef,
  flexRender,
  getCoreRowModel,
  getPaginationRowModel,
  useReactTable,
} from "@tanstack/react-table"

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
  })

  // ...
}

이렇게 하면 행이 자동으로 10개씩 페이지로 나뉘어요. 페이지 크기 커스터마이즈와 수동 페이지네이션 구현에 대한 자세한 내용은 페이지네이션 문서를 참고해요.

페이지네이션 컨트롤 추가하기

<Button /> 컴포넌트와 table.previousPage(), table.nextPage() API 메서드를 사용해 페이지네이션 컨트롤을 추가할 수 있어요.

import { Button } from "@/components/ui/button"

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
  })

  return (
    <div>
      <div className="rounded-md border">
        <Table>
          { // .... }
        </Table>
      </div>
      <div className="flex items-center justify-end space-x-2 py-4">
        <Button
          variant="outline"
          size="sm"
          onClick={() => table.previousPage()}
          disabled={!table.getCanPreviousPage()}
        >
          Previous
        </Button>
        <Button
          variant="outline"
          size="sm"
          onClick={() => table.nextPage()}
          disabled={!table.getCanNextPage()}
        >
          Next
        </Button>
      </div>
    </div>
  )
}

더 고급 페이지네이션 컴포넌트는 재사용 가능한 컴포넌트 섹션을 참고해요.

정렬 (Sorting)

email 컬럼을 정렬 가능하게 만들어 볼게요.

<DataTable> 업데이트하기

"use client"

import * as React from "react"
import {
  ColumnDef,
  SortingState,
  flexRender,
  getCoreRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
} from "@tanstack/react-table"

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const [sorting, setSorting] = React.useState<SortingState>([])

  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    onSortingChange: setSorting,
    getSortedRowModel: getSortedRowModel(),
    state: {
      sorting,
    },
  })

  return (
    <div>
      <div className="rounded-md border">
        <Table>{ ... }</Table>
      </div>
    </div>
  )
}

헤더 셀을 정렬 가능하게 만들기

이제 email 헤더 셀을 업데이트해서 정렬 컨트롤을 추가할 수 있어요.

"use client"

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

export const columns: ColumnDef<Payment>[] = [
  {
    accessorKey: "email",
    header: ({ column }) => {
      return (
        <Button
          variant="ghost"
          onClick={() => column.toggleSorting(column.getIsSorted() === "asc")}
        >
          Email
          <ArrowUpDown className="ml-2 h-4 w-4" />
        </Button>
      )
    },
  },
]

이렇게 하면 사용자가 헤더 셀을 토글할 때 테이블이 자동으로 정렬돼요(오름차순과 내림차순).

필터링 (Filtering)

테이블에서 이메일을 필터링할 검색 입력을 추가해 볼게요.

<DataTable> 업데이트하기

"use client"

import * as React from "react"
import {
  ColumnDef,
  ColumnFiltersState,
  SortingState,
  flexRender,
  getCoreRowModel,
  getFilteredRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
} from "@tanstack/react-table"

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const [sorting, setSorting] = React.useState<SortingState>([])
  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(
    []
  )

  const table = useReactTable({
    data,
    columns,
    onSortingChange: setSorting,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    getSortedRowModel: getSortedRowModel(),
    onColumnFiltersChange: setColumnFilters,
    getFilteredRowModel: getFilteredRowModel(),
    state: {
      sorting,
      columnFilters,
    },
  })

  return (
    <div>
      <div className="flex items-center py-4">
        <Input
          placeholder="Filter emails..."
          value={(table.getColumn("email")?.getFilterValue() as string) ?? ""}
          onChange={(event) =>
            table.getColumn("email")?.setFilterValue(event.target.value)
          }
          className="max-w-sm"
        />
      </div>
      <div className="rounded-md border">
        <Table>{ ... }</Table>
      </div>
    </div>
  )
}

이제 email 컬럼에 필터링이 활성화됐어요. 다른 컬럼에도 필터를 추가할 수 있어요. 필터 커스터마이즈에 대한 자세한 내용은 필터링 문서를 참고해요.

가시성 (Visibility)

컬럼 가시성 추가는 @tanstack/react-table 가시성 API를 사용하면 상당히 간단해요.

<DataTable> 업데이트하기

"use client"

import * as React from "react"
import {
  ColumnDef,
  ColumnFiltersState,
  SortingState,
  VisibilityState,
  flexRender,
  getCoreRowModel,
  getFilteredRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
} from "@tanstack/react-table"

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const [sorting, setSorting] = React.useState<SortingState>([])
  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(
    []
  )
  const [columnVisibility, setColumnVisibility] =
    React.useState<VisibilityState>({})

  const table = useReactTable({
    data,
    columns,
    onSortingChange: setSorting,
    onColumnFiltersChange: setColumnFilters,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    onColumnVisibilityChange: setColumnVisibility,
    state: {
      sorting,
      columnFilters,
      columnVisibility,
    },
  })

  return (
    <div>
      <div className="flex items-center py-4">
        <Input
          placeholder="Filter emails..."
          value={table.getColumn("email")?.getFilterValue() as string}
          onChange={(event) =>
            table.getColumn("email")?.setFilterValue(event.target.value)
          }
          className="max-w-sm"
        />
        <DropdownMenu>
          <DropdownMenuTrigger asChild>
            <Button variant="outline" className="ml-auto">
              Columns
            </Button>
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end">
            {table
              .getAllColumns()
              .filter(
                (column) => column.getCanHide()
              )
              .map((column) => {
                return (
                  <DropdownMenuCheckboxItem
                    key={column.id}
                    className="capitalize"
                    checked={column.getIsVisible()}
                    onCheckedChange={(value) =>
                      column.toggleVisibility(!!value)
                    }
                  >
                    {column.id}
                  </DropdownMenuCheckboxItem>
                )
              })}
          </DropdownMenuContent>
        </DropdownMenu>
      </div>
      <div className="rounded-md border">
        <Table>{ ... }</Table>
      </div>
    </div>
  )
}

이렇게 하면 컬럼 가시성을 토글하는 데 사용할 수 있는 드롭다운 메뉴가 추가돼요.

행 선택 (Row Selection)

이제 테이블에 행 선택을 추가해 볼게요.

컬럼 정의 업데이트하기

"use client"

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

import { Badge } from "@/components/ui/badge"
import { Checkbox } from "@/components/ui/checkbox"

export const columns: ColumnDef<Payment>[] = [
  {
    id: "select",
    header: ({ table }) => (
      <Checkbox
        checked={
          table.getIsAllPageRowsSelected() ||
          (table.getIsSomePageRowsSelected() && "indeterminate")
        }
        onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
        aria-label="Select all"
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        onCheckedChange={(value) => row.toggleSelected(!!value)}
        aria-label="Select row"
      />
    ),
    enableSorting: false,
    enableHiding: false,
  },
]

<DataTable> 업데이트하기

export function DataTable<TData, TValue>({
  columns,
  data,
}: DataTableProps<TData, TValue>) {
  const [sorting, setSorting] = React.useState<SortingState>([])
  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(
    []
  )
  const [columnVisibility, setColumnVisibility] =
    React.useState<VisibilityState>({})
  const [rowSelection, setRowSelection] = React.useState({})

  const table = useReactTable({
    data,
    columns,
    onSortingChange: setSorting,
    onColumnFiltersChange: setColumnFilters,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    onColumnVisibilityChange: setColumnVisibility,
    onRowSelectionChange: setRowSelection,
    state: {
      sorting,
      columnFilters,
      columnVisibility,
      rowSelection,
    },
  })

  return (
    <div>
      <div className="rounded-md border">
        <Table />
      </div>
    </div>
  )
}

이렇게 하면 각 행에 체크박스가 추가되고, 헤더에는 전체 행을 선택하는 체크박스가 추가돼요.

선택된 행 보여주기

table.getFilteredSelectedRowModel() API로 선택된 행의 수를 보여줄 수 있어요.

<div className="flex-1 text-sm text-muted-foreground">
  {table.getFilteredSelectedRowModel().rows.length} of{" "}
  {table.getFilteredRowModel().rows.length} row(s) selected.
</div>

재사용 가능한 컴포넌트 (Reusable Components)

데이터 테이블을 만드는 데 사용할 수 있는 컴포넌트 모음이에요. Tasks 데모에서 가져온 것이에요.

컬럼 헤더 (Column header)

어떤 컬럼 헤더든 정렬 가능하고 숨길 수 있게 만들어요.

export const columns = [
  {
    accessorKey: "email",
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Email" />
    ),
  },
]

페이지네이션

페이지 크기와 선택 개수를 포함한 페이지네이션 컨트롤을 테이블에 추가해요.

<DataTablePagination table={table} />

컬럼 토글 (Column toggle)

컬럼 가시성을 토글하는 컴포넌트예요.

<DataTableViewOptions table={table} />

더 알아보기 (Learn more)