tnks-data-table

The data table uses a custom useUrlState hook built on Next.js App Router's search params utilities to persist table state (pagination, sorting, filtering, etc.) directly in the URL.

This approach provides:

• Shareable URLs: Users can share links that preserve their exact view.
• Browser history support: Forward/back navigation works with table state changes.
• Bookmarkable states: Specific filtered views can be bookmarked.
• SEO benefits: Search engines can index specific data views.
• Type safety: Full TypeScript support via generics.

When state changes, the hook updates the URL; when the URL changes (e.g., via browser navigation), the hook updates the local state.

// Basic usage pattern
const [page, setPage] = useUrlState("page", 1);
const [dateRange, setDateRange] = useUrlState<{ from_date: string; to_date: string }>( 
  "dateRange", 
  { from_date: "", to_date: "" }
);

To maintain a clear separation of concerns, the project recommends a modular structure. The architecture is divided into five layers:

1. API Layer (src/api/): Handles all communication with the backend (e.g., add-entity.ts, fetch-entities.ts).
2. Core Components (src/components/data-table/): Reusable building blocks like data-table.tsx, pagination.tsx, and toolbar.tsx.
3. Implementation (src/app/(section)/entity-table/): Entity-specific configuration, including columns.tsx and row-actions.tsx.
4. Schema (src/app/(section)/entity-table/schema/): Zod type definitions and entity schemas.
5. Utils (src/components/data-table/utils/): Helper functions for column sizing, date formatting, URL state, and more.

src/
├── api/                       # API integration layer
├── components/                # Shared UI components
└── 📁data-table               # Core data table components
    ├── 📁hooks                # Custom React hooks
    └── 📁utils                # Utility functions and helpers

├── app/                       # Application routes
    └── 📁entity-table/        # Entity-specific implementation
        ├── 📁components/       # Entity table components (columns, actions)
        ├── 📁schema/           # Data schemas (Zod)
        └── 📁utils/            # Implementation-specific utils

The DataTable supports hierarchical data through the subRowsConfig property. This allows you to display parent-child relationships (e.g., an Order and its Items) using one of three rendering modes:

1. same-columns: Parent and subrows share the same column structure. The data must contain a subRows array (or a custom field specified by subRowsField).
2. custom-columns: Parent and subrows use different column definitions. You must provide getColumns for the parent and getSubRowColumns for the subrows.
3. custom-component: You provide a custom React component via SubRowComponent to handle the rendering of subrow data entirely.

To enable cross-page selection (selecting items across different pages of data), you must implement and provide the fetchByIdsFn prop.

<DataTable<Order, unknown>
  getColumns={getColumns}
  fetchDataFn={fetchOrders}
  fetchByIdsFn={fetchOrdersByIds}
  exportConfig={exportConfig}
  subRowsConfig={{
    enabled: true,
    mode: "same-columns", // or "custom-columns" or "custom-component"
  }}
/>

To maintain a clean separation of concerns, the following structure is recommended when implementing an entity-specific table:

src/
├── api/                       # API integration layer (add, delete, fetch)
├── components/                # Shared UI components
├── 📁data-table               # Core data table components (hooks, utils, main components)
│   └── 📁hooks                # Custom React hooks (e.g., use-table-column-resize.ts)
│   └── 📁utils                # Table utilities (export, date-format, url-state, etc.)
│   └── data-table.tsx         # Main component entry point
│   └── ...                    # Other core components (pagination, toolbar, etc.)
└── app/
    └── (section)/
        └── entity-table/      # Your specific implementation
            ├── components/    # Entity-specific columns, row actions, and popups
            ├── schema/        # Zod/TypeScript definitions for the entity
            └── utils/          # Entity-specific config and data fetching hooks

src/
├── api/                       # API integration layer
│   └── entity/                # Entity-specific API functions
│       ├── add-entity.ts      # Create operation
│       ├── delete-entity.ts   # Delete operation
│       ├── fetch-entities.ts  # List operation with filters
│       └── fetch-entity-by-ids.ts # Fetch specific entities
│
├── components/                # Shared UI components
└── 📁data-table               # Core data table components
    └── 📁hooks                # Custom React hooks for data-table
    └── 📁utils                # Utility functions and helpers
    └── data-table.tsx         # Main data table component
    └── ...
│
├── app/
│   └── (section)/
│       └── entity-table/      # Entity-specific implementation
│           ├── components/    # Entity table components
│           ├── schema/        # Data schemas
│           └── utils/         # Table configuration and data fetching