Data Table React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Data Table is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import DataTable from @/components/ui/data-table.

import { Download, Mail, Pencil, Plus, Trash2 } from "lucide-react"
import { DataTable, createColumns } from "@/components/ui/data-table"

type Client = { id: string; name: string; city: string; status: string; balance: number; lastInvoice: string | null }

const col = createColumns<Client>()
const columns = col([
  col.accessor("name", { header: "Client", filter: "text" }),
  col.accessor("city", { header: "City", filter: "multi-select" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Active: { tone: "success" }, Overdue: { tone: "danger" }, Prospect: { tone: "info" } },
    filter: "multi-select",
  }),
  col.accessor("balance", { header: "Balance", type: "currency", footer: "sum", filter: "number-range" }),
  col.accessor("lastInvoice", { header: "Last invoice", type: "relative" }),
])

export function Clients({ clients }: { clients: Client[] }) {
  return (
    <DataTable
      data={clients}
      columns={columns}
      caption="Clients"
      locale="en-US"
      selectionMode="multiple"
      searchPlaceholder="Search clients"
      quickFilters={[{ id: "overdue", label: "Overdue", columnFilter: { id: "status", value: ["Overdue"] } }]}
      toolbarActions={[{ label: "New client", icon: <Plus />, primary: true }]}
      bulkActions={(rows) => [
        { label: "Send email", icon: <Mail /> },
        { label: "Export", icon: <Download />, onSelect: () => console.log(rows) },
        { label: "Delete", icon: <Trash2 />, tone: "danger" },
      ]}
      rowActions={(row) => [{ label: "Edit", icon: <Pencil />, onSelect: () => console.log(row.id) }]}
      persistKey="clients"
    />
  )
}

Props

• data*
  T[]

  The rows. In server mode only the current page.

• columns*
  DataTableColumn<T>[]

  Each column: id, header, accessor, cell, type (text, number, currency, percent, date, datetime, relative, badge, boolean, avatar), badge map, align, width / minWidth / maxWidth, sortable, sortingFn, filter (text, select, multi-select, number-range, date-range), filterOptions, searchable, hideable, pinned, resizable, footer (sum, avg, count, min, max, a node or a function), mobile role, headerTooltip, truncate. Build them typed with createColumns<T>().

• getRowId
  (row: T) => string

  The row's key for selection and expansion (default row.id). Ids must be unique; duplicates print a dev warning.

• captiondefault ""
  string

  The table's name for screen readers; it also names the card list on phones. Always pass one.

• searchPlaceholderdefault "Search"
  string

  The toolbar search's placeholder and accessible name. The playground shows its own hint while it holds the default.

• localedefault ""
  string

  Numbers, money, dates and relative times ("$12,480.00", "6 days ago"). Empty uses the UIProvider's, then the browser's; the playground falls back to en-US.

• labels
  Partial<DataTableLabels>

  Every string, English by default (DEFAULT_DATA_TABLE_LABELS): search, columns, densities, rows per page, select all / page / row, the select-all banner, sort / filter / pin / move / hide, clear filters, empty and no results, error and retry, expand / collapse, drag announcements, plus toolbar and pagination strings passed through.

• modedefault "client"
  "client" | "server"

  client sorts, filters and pages in the browser. server does none of it locally: data is the current page, rowCount the total, and every change reaches onQueryChange (the page goes back to 1 when the search, a filter or the sort changes).

• rowCount
  number

  Server mode: the total number of matching rows (default data.length). The last page clamps to it.

• onQueryChange
  (query: DataTableQuery) => void

  Server mode: { page, pageSize, sorting, globalFilter, columnFilters } whenever one of them changes (the search arrives debounced, 300ms). Set refreshing while you fetch.

• paginationdefault "pages"
  "pages" | "load-more" | "infinite" | "none"

  pages: numbered pages with a rows-per-page picker (compact on phones). load-more: a button. infinite: loads when the end comes into view (with onLoadMore and hasMore for your own fetching). none: every row, best with virtualize.

• page
  number

  The current page, 1-based, controlled. Pair it with onPageChange.

• defaultPagedefault 1
  number

  The starting page while uncontrolled (clamped to the last page).

• onPageChange
  (page: number) => void

  Called with the new page.

• pageSize
  number

  Rows per page, controlled. Also the step of load-more.

• defaultPageSizedefault "25"
  number

  Rows per page while uncontrolled (remembered with persistKey).

• onPageSizeChange
  (pageSize: number) => void

  Called when the rows-per-page picker changes.

• pageSizeOptionsdefault "[10, 25, 50, 100]"
  number[]

  The choices in the rows-per-page picker.

• hasMore
  boolean

  load-more / infinite with your own fetching: whether more rows exist.

• onLoadMore
  () => (void | Promise<unknown>)

  load-more / infinite with your own fetching: append the next rows to data. Without it the table reveals its own data a page at a time.

• loadingMoredefault false
  boolean

  load-more / infinite: the next rows are on their way (the button shows a spinner).

• sorting
  { id: string; desc: boolean }[]

  The sort, controlled (TanStack's SortingState). Shift-click a header to add a column.

• defaultSortingdefault "[]"
  { id: string; desc: boolean }[]

  The starting sort while uncontrolled.

• onSortingChange
  (sorting: DataTableSort[]) => void

  Called with the new sort.

• globalFilter
  string

  The search, controlled. Client mode matches every word over the searchable columns' text, formatted values included, ignoring case and diacritics.

• defaultGlobalFilterdefault ""
  string

  The starting search while uncontrolled.

• onGlobalFilterChange
  (value: string) => void

  Called with the debounced search.

• columnFilters
  { id: string; value: unknown }[]

  Column filters, controlled. Values: text a string, select a string, multi-select a string[], number-range [min, max] (either may be null), date-range { from, to }.

• defaultColumnFiltersdefault "[]"
  { id: string; value: unknown }[]

  The starting filters while uncontrolled.

• onColumnFiltersChange
  (filters: DataTableColumnFilter[]) => void

  Called with the new filters.

• quickFilters
  DataTableQuickFilter<T>[]

  Toggle chips in the toolbar: { id, label, icon?, count?, filter: (row) => boolean } (client) or { id, label, columnFilter: { id, value } } (both modes; chips on the same column act like a radio).

• columnVisibility
  Record<string, boolean>

  Which columns show, controlled (false hides).

• defaultColumnVisibilitydefault "{}"
  Record<string, boolean>

  The starting visibility, e.g. { createdAt: false }. Reset in the Columns panel returns here.

• onColumnVisibilityChange
  (visibility: Record<string, boolean>) => void

  Called when a column is shown or hidden.

• columnOrder
  string[]

  Column ids in display order, controlled. Unknown ids are dropped and new columns appended, so a saved order survives column changes.

• defaultColumnOrderdefault "[]"
  string[]

  The starting order while uncontrolled; empty follows columns.

• onColumnOrderChange
  (order: string[]) => void

  Called after a drag, a Move left / right or a Move up / down.

• selectionModedefault "none"
  "none" | "single" | "multiple"

  Row selection with checkboxes (and long press on phone cards). multiple adds the header box, ranges, Ctrl/Cmd + A and the bulk bar.

• selectedKeys
  string[]

  Selected row ids, controlled. They survive paging and filtering: rows filtered out stay selected and the banner says how many are hidden.

• defaultSelectedKeysdefault "[]"
  string[]

  The starting selection while uncontrolled.

• onSelectedKeysChange
  (keys: string[]) => void

  Called with the selected ids in display order.

• selectAllScopedefault "page"
  "page" | "all"

  page: the header box selects the page and a banner offers every matching row (Gmail). all: it selects every row that passes the filters at once (client mode).

• bulkActions
  (rows: T[], keys: string[]) => ToolbarAction[]

  The toolbar's bulk mode while rows are selected: an inline band on desktop, a floating bar on phones. A danger tone stays red; a returned promise shows the button loading.

• rowActions
  (row: T) => MenuEntry[]

  A ⋯ column pinned to the end (revealed on hover and focus, always on touch; a sheet on phones), the same menu on right-click, and Shift+F10 on a focused row.

• onRowClick
  (row: T) => void

  Makes the row the target (Enter on a focused row too). With selection, Shift / Ctrl / Cmd + click selects instead.

• expandabledefault false
  boolean | ((row: T) => boolean)

  A chevron column that opens renderSubRow under the row (Right / Left arrows too); a function decides per row.

• renderSubRow
  (row: T) => ReactNode

  The expanded panel, full width, sliding open with the collapse preset.

• expandedKeys
  string[]

  Expanded row ids, controlled.

• defaultExpandedKeysdefault "[]"
  string[]

  The rows expanded at first.

• onExpandedKeysChange
  (keys: string[]) => void

  Called when a row expands or collapses.

• toolbardefault true
  boolean

  The toolbar above the table: search, quick filters, the Filters and Columns panels, page actions and the bulk bar.

• toolbarActions
  ToolbarAction[]

  Page actions; the primary one stays visible, the rest fold into ⋯ as space runs out.

• viewOptionsdefault true
  boolean

  The Columns panel: show and hide columns, drag or Move up / down to reorder, density, Reset.

• columnMenudefault true
  boolean

  The menu on each header: Sort ascending / descending, Clear sort, Filter, Pin left / right / Unpin, Move left / right, Hide.

• columnReorderdefault true
  boolean

  Drag headers sideways to reorder them (desktop). The header lifts into a floating chip while it moves.

• columnResizingdefault false
  boolean

  Drag handles on the header edges (fixed layout); double-click resets, arrows resize a focused handle. Widths are remembered with persistKey.

• density
  "compact" | "default" | "comfortable"

  Row height, controlled: 36 / 48 / 56px.

• defaultDensitydefault "default"
  "compact" | "default" | "comfortable"

  The starting row height while uncontrolled; the Columns panel switches it and persistKey remembers it.

• onDensityChange
  (density: DataTableDensity) => void

  Called when the density changes.

• variantdefault "surface"
  "plain" | "surface"

  surface: a raised panel. plain: no panel, a header band, for tables inside cards.

• stripeddefault false
  boolean

  A faint tint on every other row.

• stickyHeaderdefault true
  boolean

  The header sticks under --table-sticky-top (default var(--topbar-offset, 0px)) while the page scrolls, or at the top of maxHeight.

• stickyFirstColumndefault false
  boolean

  Pins the selection column and the first data column while the table scrolls sideways; a hairline shadow shows once rows slide under.

• maxHeightdefault 0
  number | string

  The table scrolls inside this height in px (and virtualizes against it); 0 or empty lets the page scroll.

• virtualizedefault "auto"
  boolean | "auto"

  Renders only the rows in view (overscan 10) with spacer rows, so the <table> stays semantic. auto turns on past 200 rendered rows. Phone cards use the page's scroll.

• persistKeydefault ""
  string

  Remembers column visibility, order, widths, density and page size in local storage under this key.

• loadingdefault false
  boolean

  The first load: skeleton rows in the real column layout (skeleton cards on phones).

• skeletonCountdefault 8
  number

  How many skeleton rows the first load shows.

• refreshingdefault false
  boolean

  Keeps the rows and slides a thin indeterminate bar along the top edge; sets aria-busy.

• errordefault ""
  ReactNode

  Replaces the rows with the error state and this text; pair it with onRetry.

• onRetry
  () => (void | Promise<unknown>)

  The error state's Try again; a returned promise shows it loading.

• emptyState
  ReactNode

  Shown when there is no data at all (default an EmptyState with labels.empty).

• showHeaderWhenEmptydefault false
  boolean

  With no rows to show (no data, or a search that matches nothing) the table renders the empty state alone, compact, without column headers spread over nothing. Turn it on to keep the headers above the empty state.

• noResultsState
  ReactNode

  Shown when the search or filters hide every row (default the no-results EmptyState with Clear filters).

• mobileLayoutdefault "cards"
  "cards" | "scroll"

  Below 768px: a card per row (title, subtitle, a badge or amount, up to four fields), or the table scrolling sideways.

• renderCard
  (row: T) => ReactNode

  Your own phone card instead of the column mapping.

• mobilePaginationdefault "load-more"
  "pages" | "load-more"

  How phones page through pages mode: Load more appends (the default, it feels native), pages keeps the compact pager. Server mode always pages.

• classNames
  Partial<Record<"toolbar" | "banner" | "table" | "scroll" | "header" | "head" | "body" | "row" | "cell" | "selectCell" | "actionsCell" | "subRow" | "footer" | "empty" | "cards" | "card" | "pagination", string>>

  Extra classes for the inner parts.

Parts

FAQ

Used in

More React table and list components