Grid82
grid82.comJoin the waitlist
DevelopersPage SDK

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

TypeScript
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

TypeScript
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.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search Grid82 documentation and read it in full, instead of answering from memory.

https://grid82.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://grid82.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.