TanStack Table Integration#

Zerobyte uses TanStack React Table (headless, @tanstack/react-table) to drive the Volumes, Repositories, and Notifications list pages. All three tables follow an identical controlled-state pattern: SortingState and ColumnFiltersState are held in local React useState, passed into useReactTable via the state object, and updated through onSortingChange / onColumnFiltersChange callbacks 1 2 3. Table state is not persisted across page reloads.

All three tables enable the same three row model factories:

The rendered output uses the shared Shadcn Table / TableHeader / TableBody primitives from ~/client/components/ui/table, iterated via table.getHeaderGroups() and table.getRowModel().rows with flexRender.

DataTableSortHeader Component#

Location: app/client/components/data-table-sort-header.tsx

This shared generic component handles the clickable sort-toggle header button used on every sortable column across all three tables. Its API:

DataTableSortHeader<TData, TValue>({
  column, // Column<TData, TValue> from TanStack Table
  title, // Display label (uppercased via CSS)
  sortDirection, // column.getIsSorted() → false | "asc" | "desc"
  center?, // Optional: positions the icon absolutely for centered columns
})

4

Behavior:

• Clicking calls column.toggleSorting(column.getIsSorted() === "asc"), toggling between ascending and descending.
• The icon is ArrowUp (asc), ArrowDown (desc), or ArrowUpDown (unsorted) from Lucide 5.
• When unsorted, the ArrowUpDown icon is hidden on lg+ screens and only revealed on group-hover — keeping headers uncluttered until the user hovers 6.
• The center prop renders the icon absolutely positioned to the right of the title text, preventing layout shift in centered columns like Status 7.

Per-Table Column Definitions#

Each table declares its own ColumnDef<RowType>[] constant at module level. Key differences:

Volumes (volumeColumns)#

• Columns: Name (text filter on name), Backend (exact filterFn on type), Status (exact filterFn, centered) 8.
• Default sort state: empty — no initial sort applied 9.
• Filtering UI: text <Input> for name search + two <Select> dropdowns for status (mounted / unmounted / error) and backend type 10.

Repositories (repositoryColumns)#

• Columns: Name, Backend (exact filterFn), Compression (accessorFn with alphanumeric sort), Status (accessorFn defaulting to "unknown", alphanumeric sort, exact filterFn) 11.
• Default sort state: [{ id: "name", desc: false }] — pre-sorted ascending by name on load 12.
• The Compression column is hidden on small screens (hidden sm:table-cell) 13.

Notifications (notificationColumns)#

• Columns: Name, Type (exact filterFn), Status (derived via accessorFn: getNotificationStatus, which returns "disabled" when row.enabled is false) 14.
• Default sort state: empty 15.
• Status filter options include "disabled", which is not a backend status value but is synthesized client-side 16.

Filter Controls & UX Patterns#

All three pages share the same filter UX conventions:

• Name/text search calls table.getColumn("name")?.setFilterValue(e.target.value) directly — TanStack Table's built-in string filter handles the matching 17.
• Dropdown filters (status, type/backend) use an exact-match filterFn: (row, id, value) => row.getValue(id) === value defined on the column 18.
• A "Clear filters" button appears conditionally when columnFilters.length > 0 and calls table.resetColumnFilters() 19.
• An inline empty state ("No X match your filters") with a secondary clear button is rendered as a hidden <TableRow> that becomes visible when rows.length === 0 && data.length > 0 20.
• The footer displays a live row count reflecting the current filtered result set 21.

Origin & Limitations#

Column sorting was introduced for Repositories and Volumes together in PR #808 — feat: add repositories & volumes column sorting. Notifications followed the same pattern when that page was built.

All sorting and filtering is performed client-side on data already fetched via TanStack Query (useSuspenseQuery). Table state (SortingState, ColumnFiltersState) lives in component-local useState and is reset on navigation — there is no URL synchronization or session persistence.