useTable

The primary hook — covers pagination, sorting, filtering, selection, expansion, grouping, pinning, persistence, and URL sync in one call.

The single hook that covers most use cases. Every option is optional; the returned table is a full TanStack Table instance with every feature bound.

Because TanStack Table v9 types a table as Table<TFeatures, TData>, tablecraft exports the alias TablecraftTable<TData> — the instance type with tablecraft's feature set already filled in. Use it wherever you need to name the type:

import type { TablecraftTable } from '@marvinackerman/tablecraft'

function Toolbar({ table }: { table: TablecraftTable<User> }) { /* … */ }

Signature

function useTable<TData extends RowData>(
  options: UseTableOptions<TData>
): UseTableReturn<TData>

Options

Option	Type	Description
`data`	`TData[]`	Row data (required)
`columns`	`ColumnDef<TablecraftFeatures, TData, any>[]`	Column definitions (required)
`pagination`	`PaginationOptions \| boolean`	`{ pageSize?, pageIndex? }`, or `true` (defaults), or `false` (disabled)
`manualPagination`	`boolean`	Server-driven pagination — pair with `rowCount`
`rowCount`	`number`	Total row count, used with `manualPagination`
`onPaginationChange`	`OnChangeFn<PaginationState>`	Custom pagination change handler
`sorting`	`SortingOptions \| boolean`	`{ defaultSort? }`, or `true`, or `false`
`manualSorting`	`boolean`	Server-driven sorting
`onSortingChange`	`OnChangeFn<SortingState>`	Custom sorting change handler
`globalFilter`	`boolean`	Enable global text filter
`onGlobalFilterChange`	`(value: string) => void`	Custom global filter handler
`columnFilters`	`boolean`	Enable per-column filters
`onColumnFiltersChange`	`OnChangeFn<ColumnFiltersState>`	Custom column filter handler
`rowSelection`	`RowSelectionOptions \| boolean`	`true`, or `{ defaultSelection?: RowSelectionState, enableMultiRowSelection? }`
`columnVisibility`	`ColumnVisibilityOptions \| boolean`	`true`, or `{ defaultVisibility? }`
`rowExpansion`	`RowExpansionOptions \| boolean`	`true`, or `{ defaultExpanded?, allowMultiple?, paginateExpandedRows?, getSubRows? }`
`grouping`	`GroupingOptions \| boolean`	`true`, or `{ defaultGrouping?, manualGrouping?, groupedColumnMode? }`
`columnPinning`	`ColumnPinningOptions \| boolean`	`true`, or `{ defaultPinning? }`
`columnOrder`	`ColumnOrderOptions \| boolean`	`true`, or `{ defaultOrder? }`
`rowPinning`	`RowPinningOptions \| boolean`	`true`, or `{ defaultPinning? }`
`columnResizing`	`ColumnResizingOptions \| boolean`	`true`, or `{ defaultSizing?, mode?, direction? }` — `mode` defaults to `'onEnd'`
`fuzzy`	`boolean \| FilterFn<TablecraftFeatures, TData>`	`true` loads `match-sorter` via `require()` — CJS/Node only. In ESM-only bundlers (Vite, browsers) import `fuzzyFilterFn` from `@marvinackerman/tablecraft/fuzzy` and pass that — see below.
`persist`	`'localStorage' \| 'sessionStorage' \| false`	Persist state across reloads — see Persistence & URL sync
`persistKey`	`string`	Storage key — required when `persist` is set
`persistOptions`	`PersistOptions`	Which state slices to persist
`syncUrl`	`boolean \| URLSyncOptions`	Sync state to the URL — see Persistence & URL sync

Typo-tolerant search in Vite and other ESM bundlers

fuzzy: true reaches match-sorter through require(), which throws in ESM-only bundlers. The /fuzzy entry imports it the normal way, so it works everywhere — and consumers who never use fuzzy search do not carry the code:

import { useTable } from '@marvinackerman/tablecraft'
import { fuzzyFilterFn } from '@marvinackerman/tablecraft/fuzzy'

useTable({ data, columns, globalFilter: true, fuzzy: fuzzyFilterFn })

match-sorter is an optional peer: install it only if you use this.

Usage

import { useTable } from '@marvinackerman/tablecraft'

const {
  table,          // Full TanStack table instance — TablecraftTable<TData>
  pagination,
  sorting,
  globalFilter,
  columnFilters,
  rowSelection,
  columnVisibility,
  rowExpansion,
  grouping,
  columnPinning,
  columnOrder,
  rowPinning,
  columnResizing,
  emptyState,
} = useTable({
  data,
  columns,
  pagination: { pageSize: 20 },
  sorting: { defaultSort: [{ id: 'name', desc: false }] },
  globalFilter: true,
  columnFilters: true,
  rowSelection: true,
  columnVisibility: { defaultVisibility: { email: false } },
  rowExpansion: { getSubRows: (row) => row.children },
  grouping: { defaultGrouping: ['role'] },
  columnOrder: true,
  rowPinning: true,
  columnResizing: true,
  fuzzy: true,
  persist: 'localStorage',
  persistKey: 'my-table',
  persistOptions: { sorting: true, pagination: true },
  syncUrl: true,
})

Return

`pagination`

Property	Type	Description
`pageIndex`	`number`	Current page (0-indexed)
`pageSize`	`number`	Rows per page
`pageCount`	`number`	Total pages
`canPreviousPage`	`boolean`	Can go back
`canNextPage`	`boolean`	Can go forward
`previousPage`	`() => void`	Go to previous page
`nextPage`	`() => void`	Go to next page
`setPageIndex`	`(index: number) => void`	Jump to page
`setPageSize`	`(size: number) => void`	Change page size

`sorting`

Property	Type	Description
`sortingState`	`SortingState`	Current sort state
`setSorting`	`OnChangeFn<SortingState>`	Set sort state directly
`clearSorting`	`() => void`	Clear all sorting

`globalFilter`

Property	Type	Description
`value`	`string`	Current search string
`setValue`	`(val: string) => void`	Set the search string
`clear`	`() => void`	Clear the search string

`columnFilters`

Property	Type	Description
`state`	`ColumnFiltersState`	Current per-column filter values
`setFilter`	`(columnId, value) => void`	Set a single column's filter
`clearFilter`	`(columnId) => void`	Clear one column's filter
`clearAll`	`() => void`	Clear all column filters

`rowSelection`

Property	Type	Description
`state`	`RowSelectionState`	Current selection map
`toggleRow`	`(rowId: string) => void`	Toggle a row
`toggleAll`	`() => void`	Select / deselect all
`clearSelection`	`() => void`	Clear all
`selectedRowIds`	`string[]`	IDs of selected rows
`selectedCount`	`number`	Number selected
`isSelected`	`(rowId: string) => boolean`	Check if selected

`columnVisibility`

Property	Type	Description
`state`	`ColumnVisibilityState`	Current visibility map
`toggleColumn`	`(columnId: string) => void`	Toggle a column
`showColumn`	`(columnId: string) => void`	Show a column
`hideColumn`	`(columnId: string) => void`	Hide a column
`showAll`	`() => void`	Show every column
`hiddenColumns`	`string[]`	Currently hidden column IDs

`rowExpansion`

Property	Type	Description
`state`	`ExpandedState`	Current expanded rows
`toggleRow`	`(rowId: string) => void`	Toggle expand
`expandRow`	`(rowId: string) => void`	Expand a row
`collapseRow`	`(rowId: string) => void`	Collapse a row
`clearExpansion`	`() => void`	Collapse all
`expandedRowIds`	`string[]`	IDs of expanded rows
`isExpanded`	`(rowId: string) => boolean`	Check if expanded

`grouping`

Property	Type	Description
`state`	`GroupingState`	Current grouped columns
`toggleGrouping`	`(columnId: string) => void`	Toggle group by column
`setGrouping`	`(cols: GroupingState) => void`	Set grouping directly
`clearGrouping`	`() => void`	Remove all grouping
`isGrouped`	`(columnId: string) => boolean`	Check if grouped
`groupedColumns`	`string[]`	Currently grouped column IDs

`columnPinning`

Property	Type	Description
`state`	`ColumnPinningState`	Raw TanStack pinning state
`pinStart`	`(columnId: string) => void`	Pin column to the start edge (left in LTR, right in RTL)
`pinEnd`	`(columnId: string) => void`	Pin column to the end edge (right in LTR, left in RTL)
`unpin`	`(columnId: string) => void`	Remove pin from column
`clearPinning`	`() => void`	Unpin all columns
`isPinned`	`(columnId: string) => 'start' \| 'end' \| false`	Query pin status
`startColumns`	`string[]`	Currently start-pinned column IDs
`endColumns`	`string[]`	Currently end-pinned column IDs

`columnOrder`

Property	Type	Description
`state`	`ColumnOrderState`	Current column order, as leaf column ids
`setOrder`	`(columnIds: string[]) => void`	Replace the order wholesale
`moveColumn`	`(columnId: string, toIndex: number) => void`	Move one column to a new index
`resetOrder`	`() => void`	Clear back to `[]` (TanStack's natural order)
`order`	`string[]`	Alias of `state`

An empty order (the default) is TanStack's sentinel for natural order, so moveColumn is a no-op until you seed columnOrder: { defaultOrder: [...] } — e.g. table.getAllLeafColumns().map(c => c.id). No drag-and-drop UI is provided; wire moveColumn to a drag library like dnd-kit or to plain buttons — see useColumnOrderState for the reasoning.

`rowPinning`

Property	Type	Description
`state`	`RowPinningState`	Raw TanStack row pinning state
`pinTop`	`(rowId: string) => void`	Pin a row to the top
`pinBottom`	`(rowId: string) => void`	Pin a row to the bottom
`unpin`	`(rowId: string) => void`	Remove pin from a row
`clearPinning`	`() => void`	Unpin all rows
`isPinned`	`(rowId: string) => 'top' \| 'bottom' \| false`	Query pin status
`topRows`	`string[]`	Currently top-pinned row IDs
`bottomRows`	`string[]`	Currently bottom-pinned row IDs

Rows pin to top/bottom, unlike columnPinning's start/end — see useRowPinningState for why.

`columnResizing`

Property	Type	Description
`state`	`ColumnSizingState`	Committed widths, keyed by leaf column id
`setSize`	`(columnId: string, px: number) => void`	Set a column's width directly
`resetSize`	`(columnId: string) => void`	Remove a column's override, falling back to its columnDef `size`
`resetAll`	`() => void`	Clear all overrides
`getSize`	`(columnId: string) => number \| undefined`	Committed width, or `undefined` if unset

This slice is the committed widths only — the state half of resizing. Its type is ColumnSizingReturn, not ColumnResizingReturn — the two names are easy to conflate. ColumnResizingReturn is the return type of the separate hook, useColumnResizing(table), which builds the drag handles that write into this slice; it needs the table instance rather than options and so isn't returned from useTable itself. If you hit a TS2322 between these two near-identical names, useTable().columnResizing is ColumnSizingReturn and useColumnResizing(table)'s return is ColumnResizingReturn.

`emptyState`

Property	Type	Description
`isEmpty`	`boolean`	`true` when data has 0 rows total
`isFilteredEmpty`	`boolean`	`true` when data exists but filters return 0 rows

Notes

position: sticky for pinned columns is plain CSS — tablecraft only provides state and the pixel offsets (column.getStart('start'), column.getAfter('end')). No UI lock-in.
columnPinning is also available on useQueryTable and useInfiniteTable with the identical option shape.
columnOrder, rowPinning and columnResizing are available on useServerTable (it delegates straight to useTable) and on useQueryTable (its return type extends useTable's) with the identical option shape. useInfiniteTable does not get any of the three — its return type is standalone rather than extending useTable's, so nothing forced these three onto it, and they were left out of scope deliberately rather than by oversight.
See Persistence & URL sync for persist* / syncUrl details, and State hooks if you're composing useReactTable yourself instead of using useTable.

useTable

On this page