Data Table

Next.js Data Table Page Generator

Create production-ready data table pages with:

• SSR initial data loading for fast first paint
• Simple state management (useState) as the default — SWR only when justified
• URL-based state for filters/pagination/sorting via URL params
• Centralized data-table from @/components/data-table
• Type-safe columns with TanStack Table
• Context-based actions for CRUD operations

Reusable Data-Table Component Library

The project includes a comprehensive reusable data-table component library at @/components/data-table. Always use these components — never build table UI from scratch.

Component Library Structure

components/data-table/
├── index.ts                  # Main exports (14 components)
├── types.ts                  # Shared type definitions
├── table/
│   ├── data-table.tsx        # Core TanStack Table wrapper (generic <TData>)
│   ├── data-table-bar.tsx    # Flexible 3-section toolbar (left/middle/right)
│   ├── data-table-controller.tsx # Collapsible filter pane: toggle + active-count badge + clear-all
│   └── pagination.tsx        # Server-side pagination synced to URL params
├── controls/
│   ├── search-input.tsx      # Debounced URL-synced search (default 2000ms)
│   ├── column-toggle.tsx     # Column visibility dropdown
│   ├── sort-list.tsx         # Advanced multi-column sort with drag-reorder
│   ├── column-header.tsx     # Per-column sort header dropdown
│   └── refresh-button.tsx    # Manual refresh trigger
├── filters/
│   ├── status-filter-bar.tsx # Tab-style status filters (All/Active/Inactive)
│   └── status-badge-filter.tsx # Badge-style status filters (inline mode available)
│   # Faceted single/multi filters with per-option counts: components/ui/faceted.tsx
│   # Active-filter count + clear-all: hooks/use-url-filter-count.ts
├── actions/
│   ├── selection-display.tsx # Selected count with clear button
│   ├── export-button.tsx     # CSV export of visible columns
│   ├── print-button.tsx      # HTML/PDF print of table
│   ├── enable-button.tsx     # Bulk enable with confirmation dialog
│   └── disable-button.tsx    # Bulk disable with confirmation dialog
└── ui/
    ├── button.tsx            # Custom button with icon + tooltip
    ├── status-badge.tsx      # Status indicator (Online/Offline/Warning)
    └── status-circle.tsx     # Circular status with click-filtering

Core Components and Usage

DataTable — Core Table Wrapper

import { DataTable } from "@/components/data-table";

<DataTable
  data={items}
  columns={columns}
  => setSelected(selectedRows)}
  renderToolbar={(table) => <MyToolbar table={table} />}
  isLoading={isLoading}
  enableRowSelection={true}
  enableSorting={true}
/>

Key features: Generic <TData>, column visibility, row selection, column resizing, RTL support, i18n, loading overlay.

DynamicTableBar — Flexible Toolbar Layout

import { DynamicTableBar } from "@/components/data-table";

// Header bar (search, filters, column toggle)
<DynamicTableBar
  variant="header"
  left={<SearchInput />}
  middle={<StatusBadgeFilter totalCount={25} activeCount={20} inactiveCount={5} />}
  right={<ColumnToggleButton table={table} />}
/>

// Controller bar (selection count, bulk actions) — shows accent bg when items selected
<DynamicTableBar
  variant="controller"
  hasSelection={selectedCount > 0}
  left={<SelectionDisplay selectedCount={3} i18n={{...}} />}
  right={
    <>
      <EnableButton selectedIds={ids} />
      <DisableButton selectedIds={ids} />
    </>
  }
/>

Pagination — URL-Synced Page Controls

import { Pagination } from "@/components/data-table";

<Pagination
  currentPage={page}
  totalPages={totalPages}
  pageSize={limit}
  totalItems={totalItems}
/>

Syncs page and limit URL params automatically. Supports page sizes 10/25/50/100, first/prev/next/last buttons, entry count display.

Filter Components

import { StatusBadgeFilter, StatusFilterBar } from "@/components/data-table";

// Badge-style (preferred, supports inline mode for embedding in toolbars)
<StatusBadgeFilter
  totalCount={total}
  activeCount={activeCount}
  inactiveCount={inactiveCount}
  inline={true}  // Render without wrapper for embedding in DynamicTableBar
/>

// Tab-style alternative
<StatusFilterBar totalCount={total} activeCount={activeCount} inactiveCount={inactiveCount} />

Both filter on is_active URL param and reset pagination to page 1 on change.

Faceted Filters & Collapsible Filter Pane

For any dimension beyond binary is_active — status, group, disposition, etc. — use faceted filters: a Faceted dropdown (single OR multi select) where each option shows a server-provided count (Available 12). Several faceted filters side by side are the multi-dimension "levels" of filtering (combined with AND).

When a table has 2+ filter dimensions, wrap them in the filter pane (DataTableController): a collapsible panel with a filters toggle that carries an active-filter-count badge and an inline clear-all (×), plus an optional selection-actions row. The active count and reset come from the useUrlFilterCount hook over a fixed FILTER_PARAM_KEYS list.

import { DataTableController } from "@/components/data-table";
import { useUrlFilterCount } from "@/hooks/use-url-filter-count";

const FILTER_PARAM_KEYS = ["is_active", "role", "search"] as const;
const { activeFilterCount, handleReset } = useUrlFilterCount(FILTER_PARAM_KEYS);

<DataTableController
  hasSelection={selectedIds.length > 0}
  activeFilterCount={activeFilterCount}
 
  i18n={{ toggle: "Filters", showFilters: "Show filters", hideFilters: "Hide filters" }}
  left={<SearchInput urlParam="search" debounceMs={300} />}
  filters={
    <div className="grid grid-cols-3 gap-3">
      <StatusDropdownFilter activeCount={activeCount} inactiveCount={inactiveCount} />
      <RoleDropdownFilter roleOptions={roleOptions} />
    </div>
  }
  right={(toggle) => (<>{toggle}<RefreshButton /><ColumnToggleButton table={tableInstance} /></>)}
/>

Counts are computed server-side and returned in the list envelope (one field per facet option, e.g. availableCount, busyCount), so they stay correct under pagination. See references/faceted-filters.md (the Faceted component + sortFacetedOptions + per-option counts) and references/filter-pane.md (the DataTableController + useUrlFilterCount + active-count badge + clear-all).

Search and Sort Controls

import { SearchInput, DataTableSortList, DataTableColumnHeader, ColumnToggleButton } from "@/components/data-table";

// Debounced search synced to URL ?filter= param
<SearchInput placeholder="Search..." debounceMs={2000} urlParam="filter" />

// Multi-column sort with drag reorder
<DataTableSortList sortableColumns={[
  { id: "firstName", label: "First Name" },
  { id: "role", label: "Role" },
]} />

// Per-column sort header (use in column definitions)
<DataTableColumnHeader column={column} title="Name" />

// Column visibility toggle
<ColumnToggleButton table={table} />

Sort syncs to URL: ?sort=firstName:asc,role:desc

Bulk Action Components

import { SelectionDisplay, EnableButton, DisableButton, ExportButton, PrintButton } from "@/components/data-table";

<SelectionDisplay selectedCount={3} i18n={{ selected: "{count} {item} selected", clearSelection: "Clear", itemName: "user" }} />
<EnableButton selectedIds={ids} />
<DisableButton selectedIds={ids} />
<ExportButton table={table} />
<PrintButton table={table} title="Users" />

Key Patterns

1. URL-Driven State: Search, filter, sort, pagination ALL sync to URL params
2. Generic <TData>: All components use TypeScript generics
3. i18n: Language hook integration throughout with fallback strings
4. RTL Support: ltr: / rtl: Tailwind classes throughout
5. Composition: DynamicTableBar + controls = flexible toolbars
6. Confirmation Dialogs: Bulk actions use useConfirmationDialog hook

Data Fetching Strategy

This application uses Strategy A (Simple Fetching) exclusively. All current tables use useState + server response updates.

Decision Question

Does this table's data change without user action?

Strategy A: Simple Fetching (Default — Used by All Current Tables)

• Use useState for local data management
• Update state from server mutation responses
• No automatic revalidation
• Lower complexity, no SWR dependency
• See: nextjs/references/simple-fetching-pattern.md

Strategy B: SWR Fetching (Reference Only — Requires Justification)

• Use useSWR with documented justification
• Configure appropriate revalidation triggers
• For dashboards and multi-user scenarios
• See: nextjs/references/swr-fetching-pattern.md

Decision framework: nextjs/references/data-fetching-strategy.md

Architecture Overview

app/(pages)/[section]/[entity]/
├── page.tsx                          # SSR entry point
├── context/
│   └── [entity]-actions-context.tsx  # Actions provider
└── _components/
    ├── table/
    │   ├── [entity]-table.tsx        # Main client wrapper (useState)
    │   ├── [entity]-table-body.tsx   # DataTable + columns
    │   ├── [entity]-table-columns.tsx# Column definitions
    │   ├── [entity]-table-controller.tsx # Toolbar/bulk actions
    │   └── [entity]-table-actions.tsx # Bulk action hooks
    ├── actions/
    │   ├── add-[entity]-button.tsx   # Add button + sheet
    │   └── actions-menu.tsx          # Row action menu
    ├── modal/
    │   ├── add-[entity]-sheet.tsx    # Create form
    │   ├── edit-[entity]-sheet.tsx   # Edit form
    │   └── view-[entity]-sheet.tsx   # View details
    └── sidebar/
        └── status-panel.tsx          # Stats sidebar

Quick Start

1. Gather requirements: Entity name, fields, API endpoints, actions needed
2. Generate files in order: types → server actions → page → table → columns → context → actions
3. Use data-table components from @/components/data-table — never build table UI from scratch

File Generation Order

1. Types (if not existing)

Define response types in @/lib/types/api/[entity].ts. See references/types-pattern.md.

2. Server Actions

Create server actions in @/lib/actions/[entity].actions.ts.

3. SSR Page (page.tsx)

import { auth } from "@/lib/auth/server-auth";
import { get[Entity]s } from "@/lib/actions/[entity].actions";
import { redirect } from "next/navigation";
import [Entity]Table from "./_components/table/[entity]-table";

export default async function [Entity]Page({
  searchParams,
}: {
  searchParams: Promise<{
    is_active?: string;
    search?: string;
    page?: string;
    limit?: string;
  }>;
}) {
  const session = await auth();
  if (!session?.accessToken) redirect("/login");

  const params = await searchParams;
  const pageNumber = Number(params.page) || 1;
  const limitNumber = Number(params.limit) || 10;
  const skip = (pageNumber - 1) * limitNumber;

  const data = await get[Entity]s(limitNumber, skip, {
    is_active: params.is_active,
    search: params.search,
  });

  return <[Entity]Table initialData={data} />;
}

4. Main Table Component

See references/table-component-pattern.md for the full pattern with:

• useState with initialData (Strategy A — default)
• Action handlers that return server responses
• updateItems() function for state mutation
• ActionsProvider wrapper
• Composition using DataTable, DynamicTableBar, Pagination, and filter components

5. Table Body + Columns

See references/columns-pattern.md for:

• Column definitions with updatingIds loading states
• Selection column with checkbox
• Status toggle with confirmation
• Actions column placeholder
• Use DataTableColumnHeader for sortable column headers

6. Context + Actions

See references/context-pattern.md for:

• Context provider setup
• Bulk action hooks
• Error handling patterns

7. Edit/Add Sheets

See references/edit-sheet-pattern.md for:

• Fetch-then-open pattern (load complete entity before opening sheet)
• Row actions with loading states
• Edit sheet component structure
• Form handling with server response updates

Core Principles

Server Response Updates (NOT Optimistic)

// ✅ CORRECT: Use server response
const updated = await api.put<EntityResponse>(`/entity/${id}`, body);
updateItems([updated]); // Update local state with server data

// ❌ WRONG: Optimistic update
const optimistic = { ...current, ...changes };
setData({ items: [...items.filter(i => i.id !== id), optimistic] });

Simple State Management (Default)

// React state — no SWR
const [data, setData] = useState<Response>(initialData);

const updateItems = (serverResponse: Item[]) => {
  setData(current => {
    if (!current) return current;
    const responseMap = new Map(serverResponse.map(i => [i.id, i]));
    return {
      ...current,
      items: current.items.map(item =>
        responseMap.has(item.id) ? responseMap.get(item.id)! : item
      ),
    };
  });
};

Typical Table Composition Pattern

// In [entity]-table-body.tsx — compose using data-table components
import { DataTable, DynamicTableBar, SearchInput, StatusBadgeFilter, ColumnToggleButton, RefreshButton } from "@/components/data-table";

<DataTable
  data={items}
  columns={columns}
 
  renderToolbar={(table) => (
    <>
      <DynamicTableBar
        variant="header"
        left={<SearchInput />}
        middle={<StatusBadgeFilter inline totalCount={total} activeCount={active} inactiveCount={inactive} />}
        right={
          <>
            <DataTableSortList sortableColumns={sortableColumns} />
            <ColumnToggleButton table={table} />
            <RefreshButton />
          </>
        }
      />
      {selectedCount > 0 && (
        <DynamicTableBar
          variant="controller"
          hasSelection
          left={<SelectionDisplay selectedCount={selectedCount} i18n={i18n} />}
          right={
            <>
              <EnableButton selectedIds={selectedIds} />
              <DisableButton selectedIds={selectedIds} />
            </>
          }
        />
      )}
    </>
  )}
/>

Reference Implementations

• src/frontend/app/(pages)/setting/users/ — canonical users table (Strategy A)
• src/frontend/app/(pages)/setting/roles/ — roles table (Strategy A)

Required Dependencies

Ensure project has:

• @tanstack/react-table - Table primitives
• @/components/data-table - Reusable table components (must exist)
• swr - Only if using Strategy B (SWR fetching)

Checklist

• Data fetching strategy selected (A is default)
• Types defined for entity and response
• Server actions created in lib/actions/
• SSR page fetches initial data
• Main table uses useState with initialData
• Table body composes DataTable, DynamicTableBar, filters, controls from @/components/data-table
• Actions return server response (not optimistic)
• Columns show loading state via updatingIds
• Columns use DataTableColumnHeader for sortable headers
• Context provides actions to children
• Bulk actions use EnableButton/DisableButton with confirmation
• URL params drive filtering/pagination/sorting
• Edit sheets use fetch-then-open pattern (not row.original)

References

• references/select-in-tables.md - SingleSelect in toolbar filters, MultiSelect in edit sheets
• references/faceted-filters.md - Faceted single/multi filters with per-option server counts, sortFacetedOptions, active-selection chips
• references/filter-pane.md - Collapsible DataTableController filter pane: active-filter-count badge, clear-all, multi-dimension layout, useUrlFilterCount
• references/form-sheet-guard.md - Unsaved-changes guard for Sheet/Dialog close (X, Escape, overlay click)