Table

When to use

Use Table for structured two-dimensional records with sorting, selection, trees, or virtualization. Column definitions use TanStack ColumnDef directly. Use ProTable for a complete search-toolbar-pagination page, EditableTable for editable cells, or List for a vertical item stream.

Import

Props

Events

Slots

Additional ColumnDef.meta fields:

Column geometry uses TanStack ColumnDef.size, minSize, and maxSize directly. Headers and cells receive matching inline width styles without a <colgroup>.

Composition primitives

TableRoot / TableHeader / TableBody / TableFooter / TableRow / TableHead / TableCell are seven thin
wrappers for tables whose structure is written by product code and only need the library skin. The
criterion is not that Table is too weak, it is that configuration cannot express structure: two
nested levels inside one row, a row that is entirely an editor, one record split into three rows.
Expressed as ColumnDef[] those become readable table structure translated into cell callbacks,
which only reads worse. So both routes coexist: data-driven tables that need sorting, pagination, or
pinned columns use the high-level Table, everything else uses the primitives. The skin (density
steps, separators, hover, selected background) comes from the same source as the high-level Table,
so this is not a second look-alike system.

TableRoot

TableHeader, TableBody, and TableFooter accept the native <thead>, <tbody>, and <tfoot> attributes, plus a ref.

All seven primitives take a `ref`, each landing on its own DOM node (TableRoot on the scrolling div, the rest on thead / tbody / tfoot / tr / th / td). TableRoot matters most: horizontal scroll state lives only on that overflow-x-auto div, so a hand-drawn floating horizontal scrollbar, a ResizeObserver on the container width, "scroll to column N", and two tables scrolling in sync all need it.

TableRow / TableHead / TableCell

TableRow derives its separator, hover, and stripe treatment from the section it sits in. Header rows
do not hover, do not stripe, and do not take last:border-0, because a single header row is also the last
row, and that rule would erase the bottom border of the header. Product code never has to remember
this difference.

Usage notes

• Memoize `columns`. TanStack's flexRender renders a function cell as a component type, so a changed identity unmounts and remounts the whole cell rather than re-rendering it. On a display-only table that merely burns time; with an input inside the cell it breaks behavior: a controlled input loses focus on every keystroke and the caret jumps to the end, an onBlur submit fires on the remount blur and commits a half-typed value, and an uncontrolled input snaps back to its defaultValue and loses characters. None of those symptoms point at the columns array, so debugging usually starts by blaming the input component. For the same reason, never put a per-keystroke value in the useMemo dependencies, since that is the same as no memo. Prefer uncontrolled inputs for inline editing.
• When forwarding primitive props through a thin wrapper, Omit the align from TableHeadProps and TableCellProps the same way they do: those interfaces replace the native align (a wider union that includes justify and char) with "left" | "center" | "right", so extending ThHTMLAttributes<…> directly is not assignable.
• A sticky header needs stickyHeader and maxHeight: sticky positioning requires an ancestor that actually scrolls vertically, and the shell only has overflow-x-auto with no height constraint by default. Applying [&_thead]:sticky from product code cannot reach it either, because that overflow container sits in between.
• "Horizontal scrolling inside the table plus a header pinned to the page" is not an available combination, and that is a CSS constraint rather than an implementation trade-off: overflow-x: auto makes visible on the other axis compute to auto, so that shell becomes a scrollport itself and anchors the header to it. Measured in Chromium, the header slides straight off as the page scrolls, while the same table under an overflow: visible shell stops cleanly at top: 0. stickyHeader="scrollParent" therefore drops `overflow-x-auto` from the shell and leaves horizontal overflow to the outer scroll container; stickyScrollbar has nothing to mirror in that mode and is ignored with a warning. Keep "self" plus maxHeight when the horizontal scroll has to stay inside the table.
• renderRowExtra and renderExpandedRow are two different things, and the latter does not substitute for the former: a detail panel allows one row at a time, only while expanded, and always adds an expander column. "This employment period permanently carries N certificate rows" is part of the row, not a collapsible detail.
• renderRowExtra and footer return bare `<tr>` elements; the component does not wrap them in <tr><td>, because wrapping would make "one attached row split into three cells" inexpressible. Always take the colSpan of a full-width row from the callback context: ctx.colSpan includes the automatically prepended selection, expander, and drag-handle columns, so a value computed from columns.length is one to three columns short and leaves a gap on the right.
• renderRowExtra cannot be combined with cellSpan, for the same reason as renderExpandedRow: attached rows sit between data rows and a vertical span would cross them. The combination skips merging and warns in development.
• renderRowExtra with virtual throws off the virtualizer's height estimate, which assumes one rowHeight per record when sizing its spacer rows; the symptom is drifting scroll position and blank space at the bottom. The component only warns instead of disabling the slot, because silently dropping the attached rows would be harder to diagnose than the misalignment. When the number of attached rows is fixed, set virtual.rowHeight to the combined height of the data row and its attached rows.
• The primitives have no sorting, pagination, pinned columns, or virtualization. They are only a skin. Go back to the high-level Table for those instead of rebuilding them by hand.
• The primitives default striped to false, the opposite of the high-level Table. Stripes count <tr> elements, and hand-written structures with attached or merged rows make that count disagree with the visual grouping of a record. Enable it explicitly once rows really are one record each.
• Set the minimum width of a wide table through minWidth, never through `className`: className lands on the scroll shell, so min-w-* stops the container from shrinking, scrollWidth equals clientWidth, the horizontal scrollbar never appears, and off-screen columns are clipped and unreachable. A wide browser window hides the problem entirely.
• meta.whitespace and meta.ellipsis are two mutually exclusive routes, because truncation requires a single line. For a review-style table that must wrap rather than truncate, combine whitespace: "normal", maxSize for the width cap, and verticalAlign: "top". Without top alignment the short cells in the row float on the middle line and no longer line up with the first line of the long ones.
• Width styles are emitted only for explicit size, minSize, or maxSize; this avoids TanStack's default size turning every auto-layout column into equal 150 px widths.
• Ellipsis needs a definite size, maxSize, or fixed layout. Its tooltip uses the raw string or number, not arbitrary custom-cell content.
• Sticky offsets sum getSize(), so pinned columns are forced to that width; set size explicitly and ensure content is wide enough to scroll.
• Resizing forces fixed layout. If summed widths are narrower than the container, min-w-full lets the browser stretch them and no horizontal scroll occurs.
• The cellSpan callback runs only for cells that are not already covered, so the "merge while the store matches the previous row" pattern is to return the whole run length at the start of the run (while (rows[i + n]?.store === rows[i].store) n++); the following rows are never asked. The el-table [0, 0] style is also honored: returning rowSpan: 0 hides that cell.
• cellSpan receives a rowIndex in render order (after sorting and filtering), and rows is ordered the same way. That is what avoids the classic el-table trap where enabling column sorting shifts the whole merge map: base the decision on the data, never on the original index.
• cellClassName lands on the <td> itself and sits last in the class string, so a background or text colour it returns wins over the stripe and pinned-column colours, which is exactly what full-cell colouring needs. Do not return a bg-* class on a pinned column unless you mean to replace its opaque background. The callback also runs for the built-in leading columns (__select__, __expander__, __drag__); skip them via ctx.columnId.
• meta.filterRender is a callback, not a component (the same contract as ColumnDef.cell): do not call hooks inside its body, keep state in your own control component. Clear a column filter with setValue(undefined), not with an empty string, which is a valid value meaning "filter by the empty string".
• filterPlacement="row" renders that row as <td> cells inside <thead> rather than <th>: it holds controls, not column names, and header cells would be announced as a second level of column names. The row is not rendered when no column is filterable.
• cellSpan cannot be combined with virtual or renderExpandedRow. Virtualization renders only the visible window, so a vertical span has nowhere to land, and an expanded panel inserts a <tr> between data rows that a vertical span would cross. In both cases the component skips merging and warns in development rather than rendering a misaligned table.
• With pinned columns (meta.sticky), a horizontal span must not cross the pinned boundary: pinned offsets accumulate from the unmerged column widths, so a span across the edge misplaces the cell next to it.
• Under grouped headers, pinning only applies to leaf columns. Offsets accumulate from leaf column widths, and a group name spanning several columns has no offset of its own, so it scrolls with the content while only the row of leaf headers below it stays at the edge. When combining grouped headers with pinned columns, keep the pinned ones outside any group -- a standalone column spans both header rows and reads the same.
• Sorting and filtering in a grouped header live on the leaf columns; the group cell has no sort button. A group column has no accessor, so "which column is being sorted" is undefined. Enable enableSorting on the leaf you want to sort by.
• Column widths in a grouped header belong on the leaf columns (size / minSize / maxSize). Setting them on the group does not distribute anything downward -- a group is as wide as its leaves add up to.
• A row hidden behind a vertical span is still its own row for selection and dragging; merging is purely visual.
• Virtualization requires optional @tanstack/react-virtual and is best for flat data, not trees, details, or drag-and-drop.
• Disable bordered when Table sits inside another bordered card.
• Sorting, selection, expansion, and filtering are internal unless the corresponding state and change handler are both supplied.
• rowHref uses window.location.assign; use onRowClick with router.push for SPA navigation. onRowClick takes precedence when both exist.
• A browser double-click emits two clicks first, so keep onRowClick reentrant when also using onRowDoubleClick.
• Embedded interactions are isolated by semantic selectors. Give custom clickable elements an appropriate role.
• Dragging never mutates data; write e.nextData or a server result back or the row snaps to its old place.
• Do not combine drag order with active column sorting; filtered drag also expresses order only among visible rows.
• Without getRowId, drag ids are array indices and cannot safely identify backend records.
• With dragHandle="row", Space belongs to dnd-kit and Enter activates the row; use the default cell handle to avoid conflict.
• Virtual rows outside the viewport are not drop targets and drag does not auto-page.
• Only top-level tree rows are draggable. Use Tree for hierarchical node movement.
• Current built-in Chinese control labels are "\u62d6\u62fd\u6392\u5e8f" (“Drag to reorder”), "\u5168\u9009" (“Select all”), "\u9009\u62e9\u884c" (“Select row”), "\u6536\u8d77" / "\u5c55\u5f00" (“Collapse” / “Expand”), "\u7b5b\u9009\u2026" (“Filter…”), dynamic "\u7b5b\u9009 <column>" (“Filter <column>”), and "\u8c03\u6574\u5217\u5bbd" (“Resize column”). emptyText also inherits the active locale.

Related

Book3D · ProTable · PricingTable · JsonViewer · EditableTable · List