Data Tables

If you go looking for a single <DataTable> component to drop your data into, you won't find one. That's deliberate. Every list in the Education Hub — inquiries, students, staff, applications — is a little different: different columns, different filters, different pagination. So instead of one all-knowing component bent into a hundred shapes by props, each feature assembles its own table from shared parts.

The shared parts do the boring, repetitive work — the chrome, the row models, the loading skeleton. The feature-owned parts describe what's actually unique: which columns, which filters, which cells. Once you've seen one feature's folder, you've seen them all.

The four-part folder

Every table lives in src/components/data-tables/{feature}/ and is built from four files. Using inquiry as our example:

• datatable.tsx — the orchestrator. Holds query params, fetches, builds the table, lays out the filter and the shell.
• columns.tsx — the column definitions: what each column is and how its cell renders.
• filter.tsx — the toolbar above the table: search, faceted filters, column visibility.
• cells/ — custom cell renderers like actions.cell.tsx and status.cell.tsx.

Two shared helpers tie them together: useDataTable (a thin wrapper over useReactTable) and DataTableShell (the table chrome every feature renders identically). Neither knows anything about inquiries — they're pure plumbing.

The orchestrator

The orchestrator is small on purpose. It owns the query params as local state, hands them to the feature's query hook, feeds the result into useDataTable, and renders the filter on top of the shell.

const [params, setParams] = useState<ListEnquiriesQueryParams>({ limit: 100 })
const { inquiries, loadingInquiries, fetchingInquiries } = useInquiries(params)

const table = useDataTable({
  data: inquiries?.data ?? [],
  columns: inquiryColumns,
  defaultColumnVisibility: { id: false },
})

Notice that params is typed with the generated ListEnquiriesQueryParams — the same contract the API speaks, so search, status, and date filters are all type-checked against the real endpoint. The filter receives params and setParams; when a user picks a status, it patches that state and the query refetches.

The shared hook

useDataTable exists so no feature has to repeat the same useReactTable boilerplate. It wires up the four pieces of table state — sorting, column filters, row selection, column visibility — and registers the standard row models.

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  // ...state + onChange handlers
})

Everything a feature needs from the table — selected rows, filter values, visible columns — comes off this one table instance. You'll see it passed down to both the filter and the shell.

The columns file

Columns are described with createColumnHelper, typed to the feature's DTO so every accessor is checked against a real field. The shape is consistent across the app: a select column always comes first, an actions column always comes last, and the visible columns sit in between.

const columnHelper = createColumnHelper<EnquiryDto>()

const inquiryColumns = [
  createSelectColumn<EnquiryDto>(),           // first — the checkbox
  columnHelper.accessor('name', { header: 'Name', cell: /* ... */ }),
  columnHelper.accessor('status', { header: 'Status', filterFn: 'equals', cell: /* ... */ }),
  // ...more accessors
  columnHelper.display({ id: 'actions', enableHiding: false, cell: /* ... */ }), // last
]

A few conventions worth absorbing. Headers are plain strings — header: 'Status', not a component — which keeps the file readable and the right-hand TOC of your mental model tidy. Rich cells delegate to a renderer in cells/; the status column just renders <StatusCell row={info.row.original} />. And when a cell needs shared context — an open-panel callback, the current user — it reads it from table.options.meta rather than threading props down through the shell.

The filter

The filter is the toolbar that sits above the table — and it's where most of a feature's personality lives. Inquiry's has a search box, faceted dropdowns for staff, priority and status, a date-range picker, and a column-visibility popover. The faceted filters drive TanStack's column filters via table.getColumn('status')?.setFilterValue(...); the search box drives the server params.

Search is the one piece worth a close look, because typing into it shouldn't fire a request on every keystroke. It uses a debounce from @tanstack/pacer — the input updates instantly for a responsive feel, but the params (and therefore the query) only update once typing settles, roughly 800ms later.

const [searchValue, setSearchValue] = useState(params?.search || '')

const debouncedSearch = useMemo(
  () =>
    debounce((search: string) => setParams((p) => ({ ...p, search })), { wait: 800 }),
  [setParams],
)

// <Input value={searchValue} onChange={(e) => {
//   setSearchValue(e.target.value)      // instant, local
//   debouncedSearch(e.target.value)     // settles after 800ms → refetch
// }} />

The important takeaway is where filter state lives: in local useState, not the URL. That keeps the filter self-contained and refetches snappy, with the trade-off that a filtered view isn't shareable by link and is lost on refresh. If you ever need shareable filters, that's a conscious change to make — not the default.

The shell

DataTableShell is the chrome every table renders identically, so no feature reinvents the header rows, the loading state, or the empty state. Hand it the table, the columns, and the loading flags and it produces, top to bottom:

• a total-count badge sourced from the paginated response (totalCount and a recordLabel like "inquiries"),
• a loading skeleton while isLoading is true,
• the table — header and body flex-rendered — dimmed during a background refetch, or an empty state when there are no rows,
• and the pagination footer.

<DataTableShell
  table={table}
  columns={inquiryColumns}
  isLoading={loadingInquiries}
  isFetching={fetchingInquiries}
  totalCount={inquiries?.totalCount ?? 0}
  recordLabel="inquiries"
  emptyTitle="No Inquiries Found"
/>

That isFetching flag is what fades the table to half-opacity during a background refetch — so a filter change feels alive without yanking the old rows away.

Two pagination systems

Here's the fork in the road, and the one decision you actually have to make when you build a new table. There are two pagination systems, and they don't mix.

const { params, onSearch, onNext, onPrev, canPrev } = useCursorParams(20)
// onNext pushes the current cursor onto a stack so onPrev can rewind

Where to go next