Data Table

A table with sorting, filtering, pagination, row selection and column visibility, built on TanStack Table.

Status
succeededeuler@example.com$316.00
succeededgauss@example.com$242.00
processingnoether@example.com$837.00
succeededcurie@example.com$874.00
failedturing@example.com$721.00
12 rows
Rows per page
Page 1 of 3
"use client"

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import {
  DataTable,
  DataTableColumnHeader,
  DataTablePagination,
  DataTableViewOptions,
  createDataTableColumnHelper,
  dataTableSelectColumn,
  useDataTable,
} from "@/components/ui/data-table"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { Input } from "@/components/ui/input"
import { HStack, VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"
import { DotsThreeIcon } from "@phosphor-icons/react/dist/csr/DotsThree"

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

const payments: Payment[] = [
  { id: "pay_7f3k", amount: 316, status: "succeeded", email: "euler@example.com" },
  { id: "pay_2m8q", amount: 242, status: "succeeded", email: "gauss@example.com" },
  { id: "pay_9x1d", amount: 837, status: "processing", email: "noether@example.com" },
  { id: "pay_4c6v", amount: 874, status: "succeeded", email: "curie@example.com" },
  { id: "pay_8b2n", amount: 721, status: "failed", email: "turing@example.com" },
  { id: "pay_1h5t", amount: 128.5, status: "pending", email: "riemann@example.com" },
  { id: "pay_6r9w", amount: 64, status: "succeeded", email: "hopper@example.com" },
  { id: "pay_3j7p", amount: 1250, status: "processing", email: "ramanujan@example.com" },
  { id: "pay_5s4z", amount: 19.99, status: "failed", email: "fermat@example.com" },
  { id: "pay_0y8e", amount: 432, status: "pending", email: "kepler@example.com" },
  { id: "pay_7u2a", amount: 590, status: "succeeded", email: "newton@example.com" },
  { id: "pay_2g6l", amount: 77.25, status: "succeeded", email: "galois@example.com" },
]

const currency = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" })

function PaymentActions({ payment }: { payment: Payment }) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={<Button variant="ghost" size="icon-xs" aria-label={`Actions for ${payment.id}`} />}
      >
        <DotsThreeIcon aria-hidden="true" />
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuGroup>
          <DropdownMenuLabel>Actions</DropdownMenuLabel>
          <DropdownMenuItem onClick={() => navigator.clipboard.writeText(payment.id)}>
            Copy ID
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>Open payer</DropdownMenuItem>
          <DropdownMenuItem>Download receipt</DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

const helper = createDataTableColumnHelper<Payment>()

const columns = helper.columns([
  dataTableSelectColumn<Payment>(),
  helper.accessor("status", {
    header: "Status",
    enableSorting: false,
    meta: { label: "Status" },
    cell: ({ cell }) => <Badge variant="outline">{cell.getValue()}</Badge>,
  }),
  helper.accessor("email", {
    header: ({ column }) => <DataTableColumnHeader column={column} />,
    filterFn: "includesString",
    meta: { label: "Email" },
  }),
  helper.accessor("amount", {
    header: ({ column }) => <DataTableColumnHeader column={column} />,
    meta: { label: "Amount", align: "end" },
    cell: ({ cell }) => currency.format(cell.getValue()),
  }),
  helper.display({
    id: "actions",
    enableHiding: false,
    meta: { align: "end" },
    cell: ({ row }) => <PaymentActions payment={row.original} />,
  }),
])

export default function DataTableDemo() {
  const table = useDataTable({
    data: payments,
    columns,
    getRowId: (payment) => payment.id,
    initialState: { pagination: { pageIndex: 0, pageSize: 5 } },
  })
  const email = table.getColumn("email")

  return (
    <VStack gap={4} width="100%">
      <HStack justify="between" align="center" gap={2}>
        <Input
          placeholder="Filter emails…"
          aria-label="Filter emails"
          xstyle={widths.narrow}
          value={String(email?.getFilterValue() ?? "")}
          onChange={(event) => email?.setFilterValue(event.target.value)}
        />
        <DataTableViewOptions table={table} />
      </HStack>
      <DataTable table={table} />
      <DataTablePagination table={table} pageSizes={[5, 10, 20]} />
    </VStack>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/data-table

Needs the arene setup first. Also adds Button, Checkbox, Dropdown Menu, Select, Stack, Table and Text.

Usage

import { DataTable, createDataTableColumnHelper, useDataTable } from "@/components/ui/data-table"
type Invoice = { id: string; customer: string; total: number }

const helper = createDataTableColumnHelper<Invoice>()

const columns = helper.columns([
  helper.accessor("id", { header: "Invoice" }),
  helper.accessor("customer", { header: "Customer" }),
  helper.accessor("total", { header: "Total", meta: { align: "end" } }),
])

function Invoices({ data }: { data: Invoice[] }) {
  const table = useDataTable({ data, columns, getRowId: (invoice) => invoice.id })
  return <DataTable table={table} />
}

Data Table is a TanStack Table v9 preset plus the parts that render it. useDataTable is TanStack's useTable with sorting, column and global filtering, pagination, row selection and column visibility already registered, so the state and methods for all of them are on table. You keep the table instance, and the parts only render it.

Keep columns and data stable: define them at module scope, in state, or in a useMemo. A new array on every render makes TanStack rebuild its row models each time.

Basic

DataTable renders headers and cells through the Table, and shows a full-width empty row when nothing matches.

InvoiceCustomerStatusTotal
INV-1042Euler LabsPaid$1,250.00
INV-1043Kepler OpticsPending$480.00
INV-1044Gauss & CoOverdue$2,100.00
INV-1045Curie StudioPaid$760.00
INV-1046Noether GroupPending$95.00
"use client"

import { DataTable, createDataTableColumnHelper, useDataTable } from "@/components/ui/data-table"

type Invoice = { id: string; customer: string; status: string; total: number }

const invoices: Invoice[] = [
  { id: "INV-1042", customer: "Euler Labs", status: "Paid", total: 1250 },
  { id: "INV-1043", customer: "Kepler Optics", status: "Pending", total: 480 },
  { id: "INV-1044", customer: "Gauss & Co", status: "Overdue", total: 2100 },
  { id: "INV-1045", customer: "Curie Studio", status: "Paid", total: 760 },
  { id: "INV-1046", customer: "Noether Group", status: "Pending", total: 95 },
]

const currency = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" })

const helper = createDataTableColumnHelper<Invoice>()

const columns = helper.columns([
  helper.accessor("id", { header: "Invoice" }),
  helper.accessor("customer", { header: "Customer" }),
  helper.accessor("status", { header: "Status" }),
  helper.accessor("total", {
    header: "Total",
    meta: { align: "end" },
    cell: ({ cell }) => currency.format(cell.getValue()),
  }),
])

export default function DataTableBasic() {
  const table = useDataTable({ data: invoices, columns, getRowId: (invoice) => invoice.id })
  return <DataTable table={table} />
}

Sorting

Render DataTableColumnHeader as a column's header to sort by it. Clicking cycles ascending, descending and off, and the heading carries aria-sort. sortFn picks the comparison; the preset registers alphanumeric, text, datetime and basic.

2.4.0May 12, 202518,240
2.3.1Mar 3, 202530,512
2.3.0Feb 18, 20259,875
2.2.0Nov 27, 202444,120
2.1.0Aug 9, 202412,603
"use client"

import {
  DataTable,
  DataTableColumnHeader,
  createDataTableColumnHelper,
  useDataTable,
} from "@/components/ui/data-table"

type Release = { version: string; date: Date; downloads: number }

const releases: Release[] = [
  { version: "2.4.0", date: new Date(2025, 4, 12), downloads: 18240 },
  { version: "2.3.1", date: new Date(2025, 2, 3), downloads: 30512 },
  { version: "2.3.0", date: new Date(2025, 1, 18), downloads: 9875 },
  { version: "2.2.0", date: new Date(2024, 10, 27), downloads: 44120 },
  { version: "2.1.0", date: new Date(2024, 7, 9), downloads: 12603 },
]

const day = new Intl.DateTimeFormat("en-US", { dateStyle: "medium" })
const count = new Intl.NumberFormat("en-US")

const helper = createDataTableColumnHelper<Release>()

const columns = helper.columns([
  helper.accessor("version", {
    header: ({ column }) => <DataTableColumnHeader column={column}>Version</DataTableColumnHeader>,
    sortFn: "alphanumeric",
  }),
  helper.accessor("date", {
    header: ({ column }) => <DataTableColumnHeader column={column}>Released</DataTableColumnHeader>,
    sortFn: "datetime",
    cell: ({ cell }) => day.format(cell.getValue()),
  }),
  helper.accessor("downloads", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column}>Downloads</DataTableColumnHeader>
    ),
    meta: { align: "end" },
    cell: ({ cell }) => count.format(cell.getValue()),
  }),
])

export default function DataTableSorting() {
  const table = useDataTable({
    data: releases,
    columns,
    getRowId: (release) => release.version,
    initialState: { sorting: [{ id: "date", desc: true }] },
  })
  return <DataTable table={table} />
}

globalFilterFn turns on one search across every column. empty replaces the "No results." text.

NameRoleTeam
Ada LovelaceEngineerPlatform
Grace HopperEngineerCompilers
Alan TuringResearcherCompilers
Emmy NoetherManagerPlatform
Marie CurieResearcherImaging
"use client"

import { DataTable, createDataTableColumnHelper, useDataTable } from "@/components/ui/data-table"
import { Input } from "@/components/ui/input"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

type Member = { name: string; role: string; team: string }

const members: Member[] = [
  { name: "Ada Lovelace", role: "Engineer", team: "Platform" },
  { name: "Grace Hopper", role: "Engineer", team: "Compilers" },
  { name: "Alan Turing", role: "Researcher", team: "Compilers" },
  { name: "Emmy Noether", role: "Manager", team: "Platform" },
  { name: "Marie Curie", role: "Researcher", team: "Imaging" },
]

const helper = createDataTableColumnHelper<Member>()

const columns = helper.columns([
  helper.accessor("name", { header: "Name" }),
  helper.accessor("role", { header: "Role" }),
  helper.accessor("team", { header: "Team" }),
])

export default function DataTableSearch() {
  const table = useDataTable({
    data: members,
    columns,
    getRowId: (member) => member.name,
    globalFilterFn: "includesString",
  })
  return (
    <VStack gap={4} width="100%">
      <Input
        placeholder="Search people…"
        aria-label="Search people"
        xstyle={widths.narrow}
        value={String(table.state.globalFilter ?? "")}
        onChange={(event) => table.setGlobalFilter(event.target.value)}
      />
      <DataTable table={table} empty="No one matches that search." />
    </VStack>
  )
}

Column meta

The preset types meta on every column.

KeyTypeEffect
labelstringThe column's name in the view menu and sort header
align"start" | "center" | "end"Aligns the header and every cell in the column

API reference

useDataTable

Takes every TanStack useTable option except features, which is dataTableFeatures. See the TanStack Table reference. It subscribes to all table state, so the component that calls it re-renders on every change, and the parts read the instance it returns.

createDataTableColumnHelper

createDataTableColumnHelper<TData>() is TanStack's column helper bound to the preset, so meta, sortFn and filterFn are typed against what is registered.

DataTable

Takes the table and every Table prop.

PropTypeDefault
tableDataTableInstance<TData>—
emptyReactNode"No results."

A selected row renders with TableRow's selected fill.

DataTableColumnHeader

PropTypeDefault
columnColumn—
childrenReactNodemeta.label or the id
xstyleStyleXStyles—

A column that can't sort renders its label as plain text.

DataTablePagination

PropTypeDefault
tableDataTableInstance—
pageSizesReadonlyArray<number>[10, 20, 30, 40, 50]
xstyleStyleXStyles—

It shows the row count, or how many rows are selected, then the page size, the page number and the first, previous, next and last buttons. Set the first page size with initialState.pagination on useDataTable.

DataTableViewOptions

A View button that opens a menu with a checkbox for each column that can be hidden. Columns with enableHiding: false are left out.

PropTypeDefault
tableDataTableInstance—
childrenReactNode"View"

dataTableSelectColumn

dataTableSelectColumn<TData>() returns a display column with a checkbox in each row and a select-all checkbox for the page in the header. It can't be sorted or hidden.

dataTableStyles

The style maps the parts use: empty for the empty row and sort for the header button's offsets.

Data attributes

AttributeOnEffect
data-slot="data-table"the tableData table
data-slot="data-table-column-header"a sort buttonSortable header
data-slot="data-table-pagination"the paginationPagination bar
data-slot="data-table-view-options"the triggerView menu trigger
data-selecteda rowPresent when selected