DataTable

Server-Side Pagination

The DataTable never loads the entire dataset into memory. It communicates with your Go API using query parameters for page, page size, sort, and filter values. The API returns a paginated response with a meta object containing total count, current page, page size, and total pages.

Pagination controls appear at the bottom of the table showing the current range (e.g. "Showing 1-20 of 156"), page navigation buttons, and a page size selector (10, 20, 50, 100 rows).

The default page size is controlled by table.pageSize in your resource definition (default: 20). Users can change the page size at runtime using the selector in the pagination bar.

Column Sorting

Any column with sortable: true in its definition becomes clickable. Clicking a column header cycles through three states:

1. Ascending — small arrow pointing up appears next to the header.
2. Descending — arrow points down.
3. No sort — returns to the default sort order.

Sorting sends sort and order query parameters to the API. Only single-column sorting is supported (clicking a new column clears the previous sort). You can set a default sort in the resource definition:

Column Filtering

Filters appear as a horizontal bar above the data table. Three filter types are supported, each rendering a different control:

Select Filter

Renders a dropdown with predefined options. Useful for status fields, categories, or any column with a fixed set of values.

Date Range Filter

Renders two date pickers (from and to) for filtering records within a time window. Sends created_at_from and created_at_to query parameters.

Number Range Filter

Renders two number inputs (min and max) for filtering numeric values. Useful for price ranges, quantities, or scores. Sends amount_min andamount_max query parameters.

Active filters show a count badge on the filter bar and a "Clear filters" button appears when any filter is applied. Changing filters resets the page to 1.

Show/Hide Columns

A column visibility dropdown appears in the table toolbar. Users can toggle individual columns on or off. Columns with hidden: true in their definition are hidden by default but can be shown via the dropdown. Column visibility preferences are persisted in localStorage so they survive page reloads.

Search

When table.searchable is true (the default), a search input appears in the table toolbar. Typing into it sends a search query parameter to the API. On the Go side, the search handler applies aILIKE query across all columns marked with searchable: true in the resource definition.

Search is debounced at 300ms to avoid excessive API calls while the user is typing.

Custom Cell Renderers

The format and badge column options cover most use cases. Here are examples of each renderer:

Column Styling

Add the className property to any column definition to apply custom Tailwind CSS classes to every cell in that column. This wraps the rendered content in a <span> with your classes, so it works alongside any format type.

Row Actions

Each row has an actions menu (three-dot icon) on the right side. The available actions are controlled by the table.actions array in your resource definition:

• create — adds a "New [Resource]" button to the table toolbar that opens the create form modal.
• edit — opens the edit form modal pre-filled with the row data.
• delete — shows a confirmation dialog, then sends a DELETE request to the API.
• view — navigates to a detail page for the resource.
• export — adds CSV/JSON export buttons to the toolbar.

Delete actions use optimistic updates via React Query — the row is removed from the table immediately and restored if the API call fails.

Bulk Actions

When bulkActions are defined, each row gets a checkbox on the left side. Selecting one or more rows reveals a floating action bar at the bottom of the table with the configured bulk actions. For example, selecting 5 rows and clicking "Delete" sends 5 DELETE requests in parallel.

Empty State

When a resource has no data (or no results match the current filters), the DataTable shows a polished empty state with:

• An illustration matching the resource icon
• A message like "No posts yet"
• A "Create your first post" button that opens the create form modal

The empty state maintains the table's full width and height so the layout does not collapse.

Loading Skeleton

While data is being fetched, the DataTable renders a skeleton loader that matches the exact layout of the table — header row, column widths, and row heights are preserved. This prevents layout shift when data loads and gives users confidence that content is on its way.

Subsequent page navigations (changing page, applying filters) show a subtle loading indicator in the table header instead of replacing the entire table with a skeleton. This keeps the current data visible while the new data loads.

Export to CSV / JSON

When 'export' is included in table.actions, export buttons appear in the table toolbar. Users can export the current filtered and sorted view as CSV or JSON. The export fetches all matching records from the API (not just the current page) and triggers a browser download.

Column labels are used as CSV headers. Hidden columns are excluded from the export unless explicitly shown. Badge values export as their raw value (e.g."paid") rather than the display label.

Responsive Behavior

On screens narrower than the table's natural width, the DataTable enables horizontal scrolling. The row actions column is sticky on the right side so it remains visible while scrolling. On mobile devices, the filter bar collapses into a "Filters" button that opens a sheet overlay.