Data Table

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-data-table

pnpm add @tanstack/react-table @shopify/flash-list

Usage

Headless (web API)

Like the web DataTable, the native component renders a TanStack table instance you build elsewhere — typically with useDocyrusDataTable, or directly with useReactTable.

import {
  getCoreRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
  type ColumnDef
} from '@tanstack/react-table';

import { DataTable, getDataTableSelectColumn } from '@/components/docyrus-native/data-table';

const columns: ColumnDef<Person>[] = [
  getDataTableSelectColumn<Person>(),
  { accessorKey: 'name', header: 'Name', size: 160 },
  { accessorKey: 'role', header: 'Role' },
  { accessorKey: 'status', header: 'Status' }
];

function PeopleTable({ people, isLoading }: { people: Person[]; isLoading: boolean }) {
  const table = useReactTable({
    data: people,
    columns,
    getRowId: row => row.id,
    enableRowSelection: true,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getPaginationRowModel: getPaginationRowModel()
  });

  return (
    <DataTable
      table={table}
      pagination
      isLoading={isLoading}
      maxHeight={480}
      onRowClick={row => router.push(`/people/${row.original.id}`)} />
  );
}

Convenience path

Without table, DataTable builds the instance itself from data + columns and the enable* flags / controlled state pairs.

<DataTable
  data={people}
  columns={columns}
  enableSorting
  enableRowSelection
  enableMultiRowSelection
  enableGrouping
  grouping={['role']}
  pagination={{ enabled: true, pageSize: 10 }}
  maxHeight={400} />

Layout notes

• The table card needs a bounded height: pass maxHeight, or render it in a parent with a fixed / flex height. The body is a FlashList (always virtualized).
• The header stays visible while the body scrolls (stickyHeader, default true) and uses a muted background.
• Columns pinned left (columnPinning.left) — plus the reserved select and actions columns, which are always frozen on the leading edge — stay in place while the table scrolls horizontally. columnPinning.right columns freeze on the trailing edge.
• When the columns are narrower than the screen, the scrolling (non-pinned) columns stretch to fill it.
• Grouped rows render as full-width group headers (chevron, value visual — avatar / image / icon / colour dot — label and row count). Tap a header to expand / collapse. Labels come from resolveGroupHeaderPresentation (the same helper as the web data grid), and meta.renderGroupValue is honoured except for date buckets.
• Tap a row → onRowClick(row). Long-press a row → toggles its selection (when the row can be selected). Interactive children (checkboxes, links, buttons) keep their own presses.

API Reference

DataTable — shared props

DataTable — convenience props (no table)

Controlled on*Change handlers always receive the resolved next value (never an updater function).

DataTableLegacyPagination

getDataTableSelectColumn

getDataTableSelectColumn<TData>(options?) returns the reserved select column (header checkbox toggles all page rows; cell checkbox toggles the row). DataTable always freezes it on the leading edge.

DataTablePagination

Presentational footer (also used by the convenience path's legacy pagination).

DataTablePaginationFooter

<DataTablePaginationFooter table={table} /> renders DataTablePagination from the table's own pagination state (getRowCount(), setPageIndex, setPageSize). Props: table, size?, pageSizeOptions?, className?. This is what pagination renders.

DataTableToolbar

Native-only convenience toolbar for the data/columns path. Headless tables should use the data-grid toolbar menus.

Translation keys

ui.dataTable.noResults, ui.dataTable.loading, ui.dataTable.expandGroup, ui.dataTable.collapseGroup, ui.dataTable.ungrouped, ui.dataGrid.pagination.{empty,range,pageSize,first,prev,pageOf,next,last}, ui.dataGrid.fields, ui.common.searchPlaceholder.

Breaking changes (native major)

• styles, headerStyle, bodyStyle, rowStyle, cellStyle, toolbarStyle (all any) were removed — use className, containerClassName, tableClassName, headerClassName, bodyClassName, rowClassName and cellClassName.
• onRowClick now receives the TanStack Row<TData> (web parity) instead of the raw record: use row.original.
• stickyHeader now defaults to true, and the body is always a FlashList (the non-virtualized ScrollView path and the "mobile cards" fallback were removed).
• DataTableProps no longer extends ViewProps (no ...rest spread onto the container); testID is still supported.
• data / columns are no longer required when table is passed; DataTableProps is now a union of DataTableHeadlessProps and DataTableConvenienceProps.
• With enableRowSelection, the selection checkbox is now a real select column (getDataTableSelectColumn) instead of an extra 50px cell, and a long-press toggles selection.
• Expanding uses TanStack's expanded row model (getSubRows, keyed by row id) instead of rendering original.subRows manually.
• Legacy pagination.showPrevNext is ignored.

Components

Type Exports