---
title: "Page SDK reference"
description: "Approved imports, React hooks (useTable, useRecord, useQuery, useSchema, useHost), batch writes, file uploads, and build compiler checks."
canonical: "https://grid82.com/docs/developers/sdk/page-sdk"
updated: "2026-11-20"
---

# Page SDK reference

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):

```tsx
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

```tsx
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.** `useTable` and `useQuery` automatically re-fetch within about one second whenever underlying records change. Only pass `refreshMs` (minimum `10000` ms, paused while the tab is hidden) for clock-driven displays.
- **Pagination.** Single API calls return up to `200` records. Call `loadMore()` for scrolled lists, or `loadAll()` inside `useEffect` when rendering a complete Kanban board or sum. Prefer `useQuery` for server-side aggregations (capped at `1,000` returned result rows, reported by `truncated`).
- **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 `isLoading` first, `error` second, and `rows` third (passing `isLoading` and `error` straight to `@grid82/blocks` handles 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 in `useAction`).
- **Large batches.** `createMany`, `updateMany`, and `removeMany` chunk writes into 500-record API calls (`removeMany` creates 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 on `host.can("openRecord")`).
- `navigate(pageId)` switches to another Interface page inside the same app.
- `toast(message, { kind })` and `await confirm({ title, destructive, action })` invoke native Runtime feedback and confirmation dialogs.
- `attachTo(tableId, recordId, fieldId, files)` and `detachFrom(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.
