Page SDK reference
Approved imports, React hooks (useTable, useRecord, useQuery, useSchema, useHost), batch writes, file uploads, and build compiler checks.
A Grid82 Interface page is a single .tsx file exporting a default Page React component. It executes inside a sandboxed cross-origin frame (pages.grid82.app) and accesses data strictly through the host bridge using the active user’s permissions.
Allowed module imports
Every page may import only from these approved modules (other imports fail compilation):
import * as React from "react";
import {
useTable,
useRecord,
useSchema,
useTableSchema,
useQuery,
useHost,
useAction,
actions,
createMany,
updateMany,
removeMany,
openRecord,
navigate,
toast,
confirm,
uploadFile,
attachTo,
detachFrom,
matchRows,
fmt,
} from "@grid82/sdk";
import { Button, Card, Badge, Dialog } from "@grid82/ui";
import { PageBody, PageHeader, Toolbar, DataTable, AddRecord, Kanban } from "@grid82/blocks";
import { Plus, Search } from "lucide-react";
// Loaded only when imported:
import { BarChart, LineChart, AreaChart, PieChart } from "@grid82/charts";
import { ImportDialog, readSheet, suggestMapping, coerceRows } from "@grid82/sheets";
export default function Page() {
return null;
}Reading data and host state
const {
rows,
fields,
isLoading,
error,
hasMore,
refetch,
loadMore,
loadAll,
loadingMore,
create,
update,
remove,
} = useTable("tbl_8fj3kq2wmv5d", { filter, where, search, viewId, sort, limit, refreshMs });
const { row, isLoading, error, refetch, update, remove } = useRecord(tableId, recordId);
const schema = useSchema(); // { tables: [...] } visible to current user
const table = useTableSchema(tableId); // includes canCreate, canUpdate, canDelete, and field.writable
const { rows, columns, truncated, isLoading, error } = useQuery(
"SELECT stage, COUNT(*) AS n, SUM(amount) AS total FROM deals GROUP BY stage",
[],
);
const host = useHost(); // { app, page, user, theme, can }- Live invalidation.
useTableanduseQueryautomatically re-fetch within about one second whenever underlying records change. Only passrefreshMs(minimum10000ms, paused while the tab is hidden) for clock-driven displays. - Pagination. Single API calls return up to
200records. CallloadMore()for scrolled lists, orloadAll()insideuseEffectwhen rendering a complete Kanban board or sum. PreferuseQueryfor server-side aggregations (capped at1,000returned result rows, reported bytruncated). - Strict hook property names. Destructuring nonexistent aliases (
records,loading,data) is caught and rejected at compile time so pages never silently render empty states. - Three-state rendering rule. Always handle
isLoadingfirst,errorsecond, androwsthird (passingisLoadinganderrorstraight to@grid82/blockshandles this automatically).
Writing records and batches
useTable().create/update/remove. Optimistically update UI state and roll back automatically if the server refuses (ideal for Kanban drags).actions.create/update/remove/duplicate. Async promises that resolve only after server confirmation (ideal for dialogs wrapped inuseAction).- Large batches.
createMany,updateMany, andremoveManychunk writes into 500-record API calls (removeManycreates a single changeset so users can undo the entire batch in one step) and return both succeeded and failed items. - Error fidelity. Always render permission refusals returned by the app verbatim rather than masking them behind generic success messages.
Shell actions and file uploads
openRecord(tableId, recordId)opens the native Runtime record sheet with comments and history (gate triggers onhost.can("openRecord")).navigate(pageId)switches to another Interface page inside the same app.toast(message, { kind })andawait confirm({ title, destructive, action })invoke native Runtime feedback and confirmation dialogs.attachTo(tableId, recordId, fieldId, files)anddetachFrom(tableId, recordId, fieldId, attachmentId)upload files through the parent app bridge without giving the sandboxed frame direct network credentials.
What the page compiler rejects
Pages fail compilation cleanly with line numbers if they use:
- Disallowed imports, nonexistent lucide icon names, or unknown hook destructuring keys.
- Browser escape hatches (
fetch,XMLHttpRequest,WebSocket,eval,import(),dangerouslySetInnerHTML,localStorage,document.cookie,window.parent,window.confirm). - CSS class names outside Grid82’s closed Tailwind token set unless declared inside the page’s own
<style>block.