Tables and Data grid

Choose the view

Use Table for records read across rows, with native table semantics. Its parts also work without a data engine. Use Data grid for spreadsheet navigation, cell selection and editing. Table.Data and DataGrid can consume the same caller-created TanStack Table instance. The raw grid rows/columns convenience API also creates a TanStack instance internally; it is not a second engine.

TanStack Table owns row models, column accessors and configured feature state. A row model is the current sequence of rows after configured sorting, filtering or pagination. Ghost adds table rendering or grid interaction. Your application owns fetching, authorization, persistence, validation policy and business actions.

First typed table

Follow installation for the local package artifact and shared styles. Install @tanstack/react-table@9.2.8. These examples use v9: v8 useReactTable and row-model recipes are different APIs. The package's component subpaths keep unrelated optional integrations out of the import graph.

1234567891011121314import { tableFeatures, useTable, type ColumnDef } from "@tanstack/react-table";
import { Table } from "@ghost-ui/core/components/table";

type Source = { id: string; title: string; owner: string };
const features = tableFeatures({});
const rows: Source[] = [{ id: "handbook", title: "Handbook.pdf", owner: "Mira" }];
const columns: ColumnDef<typeof features, Source>[] = [
  { accessorKey: "title", header: "Source" },
  { accessorKey: "owner", header: "Owner" },
];
export function Sources() {
  const table = useTable({ features, data: rows, columns, getRowId: row => row.id });
  return <Table aria-label="Sources"><Table.Data table={table} /></Table>;
}

accessorKey reads a property from a row. Use accessorFn with an explicit column id for computed values. Stable row and column IDs keep selection, edit targets and pinning attached to the right records when their order changes. Off-page selection retention still needs an application policy. Do not use display labels or array positions as persistent identity.

Add features deliberately

Register only the features you need in tableFeatures. Sorting needs rowSortingFeature and a sorted row model for client sorting; filters and pagination have their own feature/model pairs. A sort icon alone does not configure sorting. Define features and static columns outside render, and memoize derived data when appropriate.

Table.Data subscribes to the instance and renders headers/cells with table.FlexRender. Column definitions own values and header/cell renderers; meta.alignment and meta.widthMode add Ghost presentation choices. Use Table parts directly for a layout or cell composition outside Table.Data's contract.

Continue with state and editing. Use the TanStack v9 guides for engine details, and the component pages for anatomy and styling.

Reference and troubleshooting

TableDataProps accepts table, emptyContent, showFooter, and row/header/cell prop callbacks. DataGridTableProps accepts table plus grid interaction props, excluding raw rows/columns. Import these types from their respective component subpaths. Table API and Data grid API describe the exact view contracts.

If a feature method is missing, check its registration and the installed major version. If the data changes but an external control does not, subscribe to the relevant table state instead of reading a stale snapshot. If edits disappear, apply the edit to caller-owned data; neither view saves it.