Skip to Content

React Data Table Component

Build React data tables with asynchronous range loading, sorting, and search. Learn column definitions, row rendering, loading states, and TypeScript props.

Use the React DataTable component to render structured data in an accessible table, with optional sorting and search. Provide the total item count, column headers, a range-based loader, and a function that maps each item to its cells.

Stable API maturity: Stable. The documented public API is covered by tests and is intended to remain backward-compatible within a major version. This is an API commitment, not a guarantee of production readiness in every application.

Import

import { DataTable } from "@puzzle-ui/ui";

Basic usage

The requestItems callback receives a start index and an exclusive end index. Return the items for that range; the table requests another range when the page changes.

390 × 844

Pass getSortValue and defaultSort to enable sorting. Pass searchable and getSearchValue to show a search field. Both operations apply only to the items currently loaded by the table. DataTable does not send sort or search state with range requests, so it cannot perform global sorting or filtering on server-paginated data.

Sortable columns

Click a column heading to cycle through ascending, descending, and unsorted. defaultSort sets the initial order; getSortValue provides the value compared for each column.

390 × 844

To control the sort from a parent, provide sort (including null to enable sorting without an active order) and update it in onSortChange.

Searchable rows

Set searchable and provide getSearchValue to add a search field with a search icon. Return the text fields that should be matched for each item. Optionally set searchPlaceholder to provide a hint.

390 × 844

Column sizing and scrolling

Set columnSizes to provide a pixel width for each column or "auto" for content-based sizing. Use maxHeight to keep a long table within a scrollable viewport; the header remains visible while scrolling.

390 × 844

Initial data and loading

Pass initialItems when the first range is already available so it can render immediately. loadingContent replaces the loading message while later ranges are fetched.

390 × 844

Initial and empty content

Set noContent to replace the default empty message.

390 × 844

For paginated data, pass initialItems for the first range and keep requestItems available for subsequent pages. loadingContent customizes the loading message, and onError lets the surrounding UI respond to failed requests; the table displays a retry action by default.

API reference

DataTable props

PropTypeDefaultDescription
numberOfItemsnumber—Total number of items available.
header(string | ReactNode)[]—Column headings. Must contain at least one item.
requestItems(start: number, end: number) => Promise<T[]>—Loads the requested range; end is exclusive.
renderCell(item: T) => DataTableCellValue[]—Returns one cell value per header for an item.
columnSizes(number | "auto")[]—Column widths in CSS pixels, or content-based sizing with "auto".
itemsPerPagenumber—Number of items to request per page. When omitted, the table requests all items.
initialItemsT[]—Items already loaded for the initial range.
sortDataTableSortState | null—Controlled sort state; supplying it enables sorting.
defaultSortDataTableSortState | null—Initial uncontrolled sort state; supplying it enables sorting.
getSortValue(item: T, columnIndex: number) => string | number | null—Value used to sort an item by a column. Sorting applies to loaded items only.
onSortChange(sort: DataTableSortState | null) => void—Called when the user changes the sort.
searchablebooleanfalseShows a search field. Requires getSearchValue.
searchPlaceholderstring—Optional placeholder for the search field.
getSearchValue(item: T) => string—Text used to search an item. Search applies to loaded items only.
noContentReactNode"No items found."Content shown when there are no matching items.
loadingContentReactNode"Loading…"Content shown while items are loading.
onError(error: unknown) => void—Called when loading fails. The table shows an error message and a retry button.
maxHeightCSSProperties["maxHeight"]—Bounds the table viewport and enables vertical scrolling.
classNamestring—Additional class name for the root element.

DataTable also accepts the standard props of a div.

Exported types

  • DataTableProps<T> describes the component props.
  • DataTableCellValue is string, number, ReactNode, or null.
  • DataTableColumnSize is a width in pixels or "auto".
  • DataTableSortState contains a zero-based columnIndex and an asc or desc direction.
  • DataTableSortDirection is "asc" | "desc".

Accessibility

  • The component uses a native HTML table with column headers and sortable header buttons.
  • Search and pagination controls have accessible names.
  • Loading state is exposed through aria-busy; keep custom loading and empty content understandable without relying on visual styling alone.
  • Ensure each header clearly describes its column, and return a value for every header from renderCell.