Skip to main content

​
Overview

useTable is the React/React Native hook for a custom table’s rows, backed by RTK Query against the /db surface. It returns the current page of rows plus loading/refetch state, query controls, and row CRUD actions. The query knobs (page, limit, sort, filters, includeDeleted) are stored in the tables Redux slice keyed by table name, so multiple consumers of the same table share one view. See Custom Tables — Overview for a guide, and Custom Tables for the feature concept.

​
Usage Example

import { useTable } from "@sublay/react-js";

interface EventRow {
  id: string;
  name: string;
  capacity: number;
  createdAt: string;
}

function Events() {
  const {
    rows,
    pagination,
    loading,
    setPage,
    setSort,
    setFilters,
    createRow,
    updateRow,
    deleteRow,
  } = useTable<EventRow>("Events");

  return (
    <>
      {loading && <Spinner />}
      {rows.map((e) => (
        <Row key={e.id} event={e} onSave={(d) => updateRow(e.id, d)} onDelete={() => deleteRow(e.id)} />
      ))}
      {pagination?.hasMore && <button onClick={() => setPage(pagination.page + 1)}>Next</button>}
    </>
  );
}

​
Parameters

​
tableName
string
required
The logical custom-table name (without the custom_ prefix). Must be stable across renders.
​
options
Partial<TableViewState>
Optional initial view — any of page, limit, sortBy, sortDir, filters, includeDeleted. Used to seed the stored view the first time this table is read.

​
Return Values

​
rows
T[]
The current page of rows.
​
pagination
PaginationMetadata | null
Pagination metadata (page, pageSize, totalPages, totalItems, hasMore), or null before the first load.
​
loading
boolean
true while the current query is in flight.
​
error
unknown
The query error, if any.
​
refetch
() => void
Re-runs the current query.
​
view
TableViewState
The current stored view: { page, limit, sortBy, sortDir, filters, includeDeleted }.
​
setView
(view: Partial<TableViewState>) => void
Merge-updates the stored view.
​
setPage
(page: number) => void
Changes the current page.
​
setFilters
(filters: DbFilter[]) => void
Replaces the filter clauses (and resets to page 1). Each clause is { column, operator, value }; operators are eq, ne, gt, gte, lt, lte, in, contains, like, isNull, AND-combined.
​
setSort
(sortBy?: string, sortDir?: 'asc' | 'desc') => void
Sets the sort column/direction (and resets to page 1).
​
setIncludeDeleted
(includeDeleted: boolean) => void
On a paranoid table, toggles whether soft-deleted rows are included (resets to page 1).
​
createRow
(data: Record<string, unknown>) => Promise<T>
Inserts a row. Managed columns (id/createdAt/updatedAt/deletedAt) are server-set and rejected from the body.
​
updateRow
(rowId: string, data: Record<string, unknown>) => Promise<T>
Updates a row; updatedAt is bumped automatically on a timestamped table.
​
deleteRow
(rowId: string, opts?: { force?: boolean }) => Promise<{ deleted: boolean; soft: boolean }>
Deletes a row. Soft-deletes on a paranoid table by default; pass { force: true } to hard-delete.
​
restoreRow
(rowId: string) => Promise<T>
Clears deletedAt on a soft-deleted row (paranoid tables only).