Skip to content
WunderUI

Data Table

Pro

A table on TanStack Table for data people work with: sort, filter, search, select rows, show and pin columns, page and export, all on the keyboard.

Playground

14 rows
INV-2001Nora LindgrenPaidPro$299
INV-2002Daniel OkaforPendingCore$398
INV-2003Priya RamanPaidCore$597
INV-2004Tomás FerreiraOverduePro$299
INV-2005Maya KesslerPaidCore$398
0 of 14 rows selected
Rows per page

Installation

Data Table comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import {
  DataTable,
  DataGrid,
  DataTableBulkContext,
  DataTableColumnDef,
  DataTableColumnFooter,
  DataTableColumnMeta,
  DataTableError,
  DataTableExpandedState,
  DataTableExportContext,
  DataTableFilter,
  DataTableFilterOption,
  DataTableFiltersState,
  DataTableFooterCalculation,
  DataTablePaginationState,
  DataTablePinningState,
  DataTableProps,
  DataTableQuery,
  DataTableSelectionState,
  DataTableServerSide,
  DataTableSortingState,
  DataTableState,
  DataTableUrlStateOptions,
  DataTableVisibilityState,
} from "@wunderui/react"

Then use it:

tsx
import { DataTable, type DataTableColumnDef } from "@wunderui/react"

type Invoice = { id: string; owner: string; status: "Paid" | "Pending" | "Overdue"; amount: number }

const columns: DataTableColumnDef<Invoice>[] = [
  { accessorKey: "id", header: "Invoice" },
  { accessorKey: "owner", header: "Owner", meta: { filter: { type: "text" } } },
  { accessorKey: "status", header: "Status", meta: { filter: { type: "multiSelect" } } },
  { accessorKey: "amount", header: "Amount", meta: { numeric: true, filter: { type: "number", unit: "USD" } } },
]

// Keep `columns` and `data` stable: module constants, state or useMemo.
const invoices: Invoice[] = [
  { id: "INV-2001", owner: "Nora Lindgren", status: "Paid", amount: 897 },
  { id: "INV-2002", owner: "Daniel Okafor", status: "Pending", amount: 398 },
  { id: "INV-2003", owner: "Priya Raman", status: "Paid", amount: 597 },
]

export function Invoices() {
  return <DataTable aria-label="Invoices" columns={columns} data={invoices} getRowId={(row) => row.id} rowLabel={(row) => row.id} />
}

Expected result: You see a card with a search field, Filter, View and Export buttons, sortable columns, three invoice rows with checkboxes and a pager. Tick a row and the selection bar appears.

When to use

Use Data Table for

  • Rows people work with: sort on several columns, filter, search, select and act on many at once
  • Data that lives on a server, paged, sorted and filtered by your API
  • A table whose view should survive a reload or a shared link, with a CSV export

Use something else for

  • Table for a short list people only read, with the cells of your own markup
  • Filter Menu for one filter control for a list that is not a table

Simple table

For a plain list, switch the toolbar menus off: columns and data give you search, sort, row checkboxes and pages. It is what the Data Grid was, now the same component with fewer parts on. Drag a column edge to resize it.

6 rows
Enterprise renewalWon$41,200
Pilot rolloutOpen$8,900
Team expansionOpen$24,800
0 of 6 rows selected
Rows per page

Filters

A column with a filter setting can be filtered. The Filter button lists those columns, and every filter becomes a chip you can edit or remove.

3 rows, filtered
INV-2001Nora LindgrenPaidPro$299
INV-2006Nora LindgrenPendingCore$597
INV-2011Nora LindgrenPaidCore$398
0 of 3 rows selected
Rows per page

Sorting

Click a header to sort: ascending, descending, off. Shift-click, Shift+Enter or Then by in the column menu adds a column, and a small number shows the order.

14 rows
INV-2001Nora LindgrenPaidPro$299
INV-2002Daniel OkaforPendingCore$398
INV-2003Priya RamanPaidCore$597
INV-2004Tomás FerreiraOverduePro$299
INV-2005Maya KesslerPaidCore$398
0 of 14 rows selected
Rows per page

Selection

Row checkboxes, shift-click for a range, and a floating bar at the bottom of the table with your bulk actions, Select all and Export selected. Selection is kept by row id, so it survives paging and sorting.

14 rows
INV-2001Nora LindgrenPaidPro$299
INV-2002Daniel OkaforPendingCore$398
INV-2003Priya RamanPaidCore$597
INV-2004Tomás FerreiraOverduePro$299
INV-2005Maya KesslerPaidCore$398
2 of 14 rows selected
Rows per page

Columns

The View menu shows and hides columns, and the column menu pins one to the start or end. The checkbox column always stays first, and the last visible column cannot be hidden.

14 rows
INV-2001Nora LindgrenPaid$299
INV-2002Daniel OkaforPending$398
INV-2003Priya RamanPaid$597
INV-2004Tomás FerreiraOverdue$299
INV-2005Maya KesslerPaid$398
0 of 14 rows selected
Rows per page

Editable cells

Put Cell Select, Cell Switch, Cell Slider or Cell Color Picker in a column to edit a value in place. The table holds the rows, the cell reports the change, and your state writes it back.

4 rows
Role
Alerts
Label
Nora Lindgren
80
Daniel Okafor
55
Priya Raman
30
Tomás Ferreira
12
0 of 4 rows selected
Rows per page

The cells are separate components: Cell Select, Cell Switch, Cell Slider and Cell Color Picker.

Data source

By default the table pages, sorts and filters the rows you pass. In server mode it tells you what to ask for through a query change handler, and your data and row count are the answer.

14 rows
INV-2001Nora LindgrenPaidPro$299
INV-2002Daniel OkaforPendingCore$398
INV-2003Priya RamanPaidCore$597
INV-2004Tomás FerreiraOverduePro$299
INV-2005Maya KesslerPaidCore$398
0 of 14 rows selected
Rows per page

States

Loading, empty, no results and error are built in and keep the toolbar and header. Each one says what happened and what to do next.

14 rows
INV-2001Nora LindgrenPaidPro$299
INV-2002Daniel OkaforPendingCore$398
INV-2003Priya RamanPaidCore$597
INV-2004Tomás FerreiraOverduePro$299
INV-2005Maya KesslerPaidCore$398
0 of 14 rows selected
Rows per page

Cards on small screens

Set mobileLayout to cards and a table narrower than 640 px shows every row as a card: the first column is the title and the other columns are label and value. Wider, the table stays, and without the prop nothing changes.

4 rows
  • Enterprise renewal
    Stage
    Won
    Owner
    Nora Lindgren
    Value
    $41,200
  • Pilot rollout
    Stage
    Open
    Owner
    Daniel Okafor
    Value
    $8,900
  • Team expansion
    Stage
    Open
    Owner
    Priya Raman
    Value
    $24,800
  • Brennholt rollout
    Stage
    Lost
    Owner
    Tomás Ferreira
    Value
    $1,500
Enterprise renewalWonNora Lindgren$41,200
Pilot rolloutOpenDaniel Okafor$8,900
Team expansionOpenPriya Raman$24,800
Brennholt rolloutLostTomás Ferreira$1,500
0 of 4 rows selected

Calculations and row numbers

Set columnFooter and a row under the table shows a calculation per column: count, sum, average, minimum or maximum, picked from the menu in each footer cell. It counts every row after search and filters, on all pages, and footerFormat in the column meta writes the number like the cells. Set rowNumbers for a narrow first column with each row's position, and meta.icon for an icon before a header label.

Calculations

6 rows
Row number
1Enterprise renewalWonNora Lindgren$41,200
2Pilot rolloutOpenDaniel Okafor$8,900
3Team expansionOpenPriya Raman$24,800
4Brennholt rolloutLostTomás Ferreira$1,500
5Calderwick seatsWonMaya Kessler$12,400
6Ostberg Freight auditOpenNora Lindgren$900
0 of 6 rows selected

URL state

The useDataTableUrlState hook keeps page, order, filters and search in the address bar, so a view can be linked and reloaded. It has its own page, and the table takes two props from it.

Keyboard interactions

The table is one grid with one tab stop: Tab enters it once and leaves it once, however many rows there are. The toolbar, chips and pager are ordinary tab stops before and after it.

TaborShiftTab
Enters the grid on the last active cell (the first header cell to begin with) and leaves it on the next Tab. Between the toolbar, the chips, the grid and the pager it moves in reading order.
ArrowRightorArrowLeftorArrowDownorArrowUp
Moves to the neighbouring cell. At an edge it stays where it is.
HomeorEnd
First or last cell of the row.
CtrlHomeorCtrlEnd
First or last cell of the grid on this page.
PageUporPageDown
Ten rows up or down, or to the first or last row.
EnterorSpace
Does the main thing of the cell: sorts the column on a header, ticks the checkbox on a row, opens or closes a row with a chevron. A cell with several controls and no main one moves focus into the cell instead.
ShiftEnter
On a header, adds the column to the sort instead of replacing it. A number then shows the order.
F2
Moves focus to the first control of the cell, such as the column menu of a header. Tab and Shift+Tab then walk the controls of that cell.
Arrow LeftorArrow Right
On a focused resize handle (reached with F2 from a header cell), makes the column 8 px narrower or wider; with Shift 32 px. Only with resizableColumns.
HomeorEnd
On a focused resize handle, sets the column to its minimum width or back to its start width. Double-click on the handle also resets the column.
Esc
From a control inside a cell, returns focus to the cell. In an open menu or the filter popover it closes the popup and returns focus to its button.

Behavior and motion

What the table does with its state, its rows and its data, and what it leaves to you.

State
Each part of the state (sorting, filters, search, columns, selection, paging, pinning, expanded rows) is controlled when you pass its value and change handler, and kept by the table otherwise.
Page resets
A new sort, filter or search goes back to the first page. If the current page disappears, the table steps back to the last one, except with server paging where you own the page.
Query callback
The query callback fires when the page, order, a filter or the search changes, but not on the first render. It is the one callback to fetch from.
Selection
Selection is kept by row id and survives paging and sorting. The header checkbox ticks the page, shift-click ticks a range, and Select all ticks every filtered row (left out with server paging).
Filters and search
Search covers the text and number columns. Filters can be text, one choice, several choices or a number range, with choices and counts read from the loaded rows unless you list them.
Columns
Columns default to 160 px and the rest of the row is shared. A data column without its own minSize gets one from its header label, so the label, the sort arrow and the column menu always fit, also below a narrow size. A wide table scrolls inside its box, and columns can be hidden or pinned to either end.
Column menu
The chevron of the column menu shows while the header cell is hovered or holds the focus and while the menu is open, and always on touch screens. It only fades (opacity), so it keeps its room and nothing moves, and it stays reachable from the keyboard (F2, then Tab in the header cell).
Expanded rows
An opened panel is as wide as the visible part of the table and sticks to its start edge, so nothing in it is off-screen while a wide table scrolls sideways.
Phone cards
With mobileLayout cards, text fields sit three to a row and truncate with the full text as title. A field whose cell draws more than text (an icon, an image, a control, or a library part such as a badge, avatar or chart) takes the whole row and wraps. Expandable rows keep their toggle in the card and open the panel inside it, and the footer calculations follow as a summary under the cards.
Server-side data
With server-side data the table does not sort, filter or page. It reports the query and shows the data and row count you pass, so keep loading on until the answer arrives.
States
Loading draws skeleton rows, Empty says there is no data, No results offers Reset filters, and Error offers Try again when a retry handler is set. Export is disabled in all four.
Announcements
A hidden status line reads the row count, Loading rows or the error, and the action bar count is a polite live region. The grid also reports row and column counts, selection and sort order.
Export
Export writes a CSV of the visible columns in their order, with header labels and a byte order mark so Excel reads UTF-8. Export selected writes only the selected rows.
Limits
Every row of the current page is rendered and nothing is virtualised, so for very large data use server-side mode. Inline editing and column resizing are not part of the table.
Motion
The action bar fades in and slides up 8 px, and an opened row fades in while its chevron turns. With reduced motion the slide and fades are off and the chevron turns at once.

Anatomy

The figure shows a filtered table with one row selected, so the chip and the action bar appear. The loading, empty and error rows replace the rows and have no number.

4 rows, filtered
INV-2002Daniel OkaforPendingCore$398
INV-2006Nora LindgrenPendingCore$597
INV-2010Maya KesslerPendingPro$299
INV-2014Tomás FerreiraPendingCore$398
1 of 4 rows selected
Rows per page
  • data-slot="data-table"

    The whole table in one bordered box: a toolbar, filter chips, the grid, an action bar while rows are selected, and a footer. Its state reads ready, loading, empty or error.

  • Optional

    A toolbar named Table tools: search on the left, then Filter, View, Export and any actions you pass in. Each control can be turned off.

  • Optional

    The field that filters every row by the text of the text and number columns. A new search goes back to the first page.

  • data-slot="data-table-filter-trigger"Optional

    Opens a list of filterable columns. Choosing one opens its editor: a text field, a list of choices or a minimum and maximum, and the button shows how many filters are active.

  • data-slot="data-table-view-trigger"Optional

    A menu of checkboxes that shows and hides columns. It never lets the last visible column go.

  • data-slot="data-table-export"Optional

    Saves every row, after filtering and sorting, as a CSV of the visible columns. It is disabled while loading, on an error and with no rows, and a custom export handler replaces the download.

  • data-slot="data-table-filter-chip"Optional

    One chip per active filter: the column, how it matches (is, is any of, contains, between) and the value. The label opens the editor, the cross removes it, and Reset filters clears all.

  • data-slot="data-table-sort"

    A column header with the sort button, a direction icon and, once two columns are sorted, a number for the order. Every sortable header reports its sort order.

  • data-slot="data-table-column-menu"Optional

    A small button beside each heading with sort ascending or descending, Then by, Clear sort, Pin to start or end, and Hide column.

  • One row of cells. It turns page tone on hover and subtle tone while selected, and the first data column is primary text with the rest secondary.

  • data-slot="data-table-details"Optional

    The panel under an opened row, drawn by a sub row renderer. A chevron column is added when you pass one.

  • data-slot="data-table-action-bar"Optional

    A floating bar named Selection actions with the count, your bulk actions, Select all, Export selected and Clear. It sticks to the bottom of the screen while the table runs past it.

  • How many rows are selected out of the total, or just the row count when selecting is off.

  • Optional

    Rows per page and the page buttons. Turning paging off removes both and shows every row.

  • Optional

    Replaces the rows: skeleton rows while loading, an empty state, a No results state with Reset filters, and an error with Try again when you pass a retry handler. Toolbar and header stay.

  • data-slot="data-table-details-content"Optional
  • data-slot="data-table-cards-view"Optional
  • data-slot="data-table-cards"Optional
  • data-slot="data-table-card"Optional
  • data-slot="data-table-card-expand"Optional
  • data-slot="data-table-card-field"Optional
  • data-slot="data-table-card-value"Optional
  • data-slot="data-table-card-details"Optional
  • data-slot="data-table-cards-footer"Optional
  • data-slot="data-table-header-icon"Optional
  • data-slot="data-table-footer"Optional
  • data-slot="data-table-status"Optional
  • data-slot="data-table-footer-menu"
  • data-slot="data-table-resize"
  • data-slot="data-table-cards-loading"Optional
  • data-slot="data-table-cards-empty"Optional
  • Optional

Best practices

  • Do

    Name the grid with an aria-label and each row with a row label, so a checkbox reads Select INV-2001 instead of Select row 3.

  • Do

    Pass a stable row id. Selection is kept by id, so without it a selection follows the position of a row when you sort or page.

  • Do

    Keep columns and data stable: module constants, state or useMemo. A new array on every render makes the table recompute its rows.

  • Do

    Turn on resizableColumns where people compare long values, and give the first column a start width that fits its longest text. Every column keeps at least 80 px, so a table with many columns scrolls sideways instead of cutting text.

  • Don’t

    Don't turn on resizableColumns for a table with two or three short columns. The handles add a focus stop per column and nothing to resize.

  • Do

    Pass loading, an error with a retry handler and, where it helps, an empty state. The table draws the skeleton rows, the alert and the empty message itself and keeps the toolbar.

  • Do

    With server-side data, list the choices of a select filter yourself. The loaded rows are only one page, so reading the choices from them would hide most of them.

  • Do

    Keep the query in the address bar with the URL state hook, under its own prefix, so a reload or a shared link opens the same view.

  • Don’t

    Don't sort, filter or page the rows yourself before passing them in. Let the table do it, or use server-side mode and answer the query callback with the matching page.

  • Don’t

    Don't put thousands of rows on one page with paging off. Every row is rendered, because the table does not virtualise.

  • Don’t

    Don't rely on the table for inline editing or column resizing. Neither exists; a cell can hold a control, but the table does not manage it.

  • Do

    Format footer totals with meta.footerFormat (the same format as the cells), hide the "n rows" line with showRowCount={false} when the footer or the page says it, and set density instead of overriding --row-py.

API reference

DataTable is a plain component, so this table lists every prop. Column definitions are TanStack column definitions with extra meta keys.

The whole table in one bordered box: a toolbar, filter chips, the grid, an action bar while rows are selected, and a footer. Its state reads ready, loading, empty or error.

PropTypeDefaultDescription
columns requiredDataTableColumnDef<TData>[]—The column definitions. Plain TanStack column objects (, , , ) or the output of ; collect those with so every keeps its accessor's type (a cast to turns it into ). makes a column filterable, right-aligns it, names it in menus, chips and the CSV header, and sets what the CSV writes. Without , a data column's minimum width comes from its header label. Keep the reference stable.
data requiredTData[]EMPTY_DATAThe rows. Keep the reference stable: a new array on every render makes the table recompute. With this is one page, already in order.
getRowId(row, index) => string—Returns a stable id for a row. Selection is kept by this id, so it survives paging and sorting; without it the id is the row index.
aria-labelstring—The accessible name of the grid. Give every table a distinct one; it is by default.
rowLabel(row) => string—Names a row for assistive technology: the checkbox reads instead of .
bulkActions(context) => ReactNode—Buttons for the floating bar that appears while rows are selected. It gets the selected rows that are loaded, the ids of every selected row (also on other pages) and .
serverSideDataTableServerSide—Hands paging, sorting and filtering to your API. means all three; an object picks , or . is then one page.
rowCountnumber—The total number of rows on the server. Needed for the page count when the server pages.
loadingbooleanfalseShows skeleton rows in place of the rows, sets and announces Loading rows. Export is disabled.
errorboolean | string | DataTableError—Shows the error state instead of the rows. uses the default text, a string becomes the description, an object sets and .
onRetry() => void—Called by Try again in the error state. Without it the error has no button.
initialStatePartial<DataTableState>—Starting values for the state you do not control: , , , , , , and . It is read once.
onQueryChange(query) => void—Called when the page, the order, a filter or the search changes, and not on mount. It is the one callback to fetch from.
columnDividersbooleanfalseDraws a thin vertical line between every pair of columns instead of only at the edges of pinned columns.
columnFiltersColumnFiltersState—The column filters as TanStack state: . Pass it with to control it.
columnFooterDataTableColumnFooter—A footer row under the rows with a calculation per column (count, sum, average, minimum, maximum), picked from a menu in each footer cell. It counts every row after search and filters, on all pages (on server pages, the loaded page). Defau…
columnPinningColumnPinningState—Which columns are pinned: . Pass it with to control it. The checkbox and expander columns are always first and are not listed.
columnVisibilityColumnVisibilityState—Which columns are hidden: . Pass it with to control it.
columnVisibilityMenubooleantrueShows the View menu. Default .
density"compact" | "default" | "relaxed""default"Row padding: (4 px, rows ≈ 29 px), (the density token, 6 px), (14 px, rows ≈ 49 px). Only the rows change; the toolbar and the controls keep their size.
emptyStateReactNode—Replaces the default No data yet state, which shows when there are no rows and no filter or search is active.
expandedExpandedState—Which rows are open, as TanStack state. Pass it with to control it.
exportablebooleantrueShows the Export button and Export selected. Default .
exportFileNamestring"table"The name of the CSV file, without the extension. Default .
getRowCanExpand(row) => boolean—Which rows can open. Default: all of them. Only read when is set.
globalFilterstring—The search text. Pass it with to control it.
loadingRowsnumber—How many skeleton rows to draw while loading. Default: the page size, at most 8.
mobileLayout"table" | "cards""table" shows every row as a card while the table is narrower than 640 px: the first column is the title, the other columns are label and value. Text fields share a row three by three and truncate; fields that draw more than text (icons, controls, badges, avatars, charts) take the whole row and wrap. The expand toggle sits in the card and the footer becomes a summary under the cards. Default .
onColumnFiltersChange(next) => void—Called with the next column filters.
onColumnPinningChange(next) => void—Called with the next pinning state.
onColumnVisibilityChange(next) => void—Called with the next visibility state.
onExpandedChange(next) => void—Called with the next expanded state.
onExport(context) => void—Called instead of the file download. It gets the scope (, or ), the rows, the CSV text and the file name.
onGlobalFilterChange(next) => void—Called with the next search text.
onPaginationChange(next) => void—Called with the next page and page size.
onRowSelectionChange(next) => void—Called with the next selection, an object of selected row ids.
onSortingChange(next) => void—Called with the next sorting.
pageSizeOptionsnumber[]DEFAULT_PAGE_SIZESThe choices in Rows per page. Default ; the current page size is added when it is not listed.
paginatedbooleantrueShows the footer pager. shows every row at once. Default .
paginationPaginationState—The page and page size as TanStack state: . Pass it with to control it.
pinnablebooleantrueShows Pin to start and Pin to end in the column menus. Default .
renderSubRow(row) => ReactNode—Draws a panel under a row when its chevron is opened. Passing it adds the expander column. The panel is as wide as the visible part of the table and sticks to its start edge while a wide table scrolls.
resizableColumnsbooleanfalseA handle on the edge of every header cell. Drag it, or focus it and use the arrow keys; double-click resets the column. The minimum is 80 px. Default .
rowNumbersbooleanfalseA narrow first column with the row's position, 1 to n, in the current order and across pages. Default: off.
rowSelectionRowSelectionState—The selected rows as an object of ids. Pass it with to control it.
searchablebooleantrueShows the search field. Default .
searchPlaceholderstring"Search…"The placeholder of the search field. Default .
selectablebooleantrueRow checkboxes, shift-click ranges and the floating action bar. Default .
showRowCountbooleantrueThe "n rows" (or "n of m rows selected") line under the table. Set to false when the footer row or the page says it already; without pagination the bar under the table is then left out. Default: true.
sortingSortingState—The sort order as TanStack state: . Pass it with to control it.
toolbarActionsReactNode—Extra buttons at the right end of the toolbar.

PropTypeDefaultDescription
columns requiredDataGridColumn<T>[]—
data requiredT[]—
pageSizenumber5Rows per page. Default 5.
searchablebooleantrueSearch field above the grid (uses each column's filterValue). Default true.
selectablebooleantrueRow checkboxes and the "n of m selected" footer. Default true; false shows the row count instead.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("data-table")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.