---
title: "Page UI kit and blocks"
description: "Schema-aware blocks from @grid82/blocks, styled primitives from @grid82/ui, design tokens, charts, and spreadsheet import helpers."
canonical: "https://grid82.com/docs/developers/sdk/page-ui-and-blocks"
updated: "2026-11-20"
---

# Page UI kit and blocks

Interface pages share the exact UI system used by Grid82's Studio and Runtime so custom pages look and behave like native screens out of the box.

## High-level schema blocks (`@grid82/blocks`)

Prefer `@grid82/blocks` for record UI because every block reads field types, select tints, permissions (`canCreate` / `writable`), and loading/error states directly from your schema:

| Block                                     | Purpose                                                                                                                                                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PageBody`, `PageHeader`, `Section`       | Page spacing rhythm (one `h1`, description, and right-aligned actions)                                                                                                                                                                            |
| `Toolbar`                                 | Search input paired with schema-driven select/user filter chips                                                                                                                                                                                   |
| `DataTable`                               | Sortable table view formatted per field type, with optional groups (`groupBy`) and loading and error states                                                                                                                                       |
| `Kanban`                                  | Column board grouped by a `select` field. With only `tableId` and `groupBy` it reads every row, moves a card on drop, opens it on click and adds one from each column. Put an `AddRecord` in the page header too, to add without picking a column |
| `RecordList`, `RecordCards`, `RecordCard` | List and visual card views (use card grids when records hold attachments)                                                                                                                                                                         |
| `AddRecord`, `RecordDialog`               | The "Add" button with its dialog, and the dialog alone to add or edit a record                                                                                                                                                                    |
| `RecordForm`, `RecordSheet`               | A schema-driven form that is the page itself, and a record's side panel (including file attachments)                                                                                                                                              |
| `StatRow`, `Stat`                         | Tabular KPI summary row                                                                                                                                                                                                                           |
| `FieldValue`, `FieldInput`                | Read and write controls automatically tailored to all 28 field types                                                                                                                                                                              |
| `EmptyState`, `ErrorState`                | Standardized empty and error presentations                                                                                                                                                                                                        |

Blocks that draw rows read their table themselves when you pass no `rows`, and a click on a record opens it in a side panel unless you pass `onOpen` (a function, or `false`). Use `useView(tableId, { filterBy })` from `@grid82/sdk` when the page needs a search box, filter chips or a sort: spread `view.toolbar` into `Toolbar` and `view.bind` into the block.

`RecordCalendar` puts each record on the day of a date field, a month at a time. `DataTable` takes `groupBy`, `totals` (number fields summed in a last row) and `selected` / `onSelectedChange` for ticked rows. `useView(tableId, { filterBy, dateBy })` adds filter chips and a period chip (today, this week, this month…) to the `Toolbar`. A block that stops at the first 200 rows offers the rest itself. Charts accept the result of `useQuery` directly (`data={query}`) and then draw their own loading, error and empty states; `labelsFrom={{ tableId, fieldId }}` shows a select's labels and colours.

When a change is about the inside of a block and no prop covers it (the border of a card, a total under a column, a column that folds), the assistant copies the block's code into the page and edits it there. `Kanban`, `DataTable`, `RecordList`, `RecordCards`, `RecordCalendar`, `RecordDialog` and `AddRecord` can be copied. The page then owns that code: it keeps working, and it no longer receives later improvements to the block.

```tsx
const deals = useView("tbl_...", { filterBy: ["fld_..."] });

<PageHeader title="Deals" actions={<AddRecord tableId="tbl_..." />}>
  <Toolbar {...deals.toolbar} />
</PageHeader>
<DataTable {...deals.bind} groupBy="fld_..." />
```

## UI primitives (`@grid82/ui`)

Built on shadcn + Base UI with Grid82 theme tokens:

- **Actions.** `Button` (`default`, `outline`, `ghost`, `secondary`, `destructive`, `link`), `ButtonGroup`, `ToggleGroup`. Keep one primary filled button per screen and label icon-only buttons with `aria-label`.
- **Badges and code.** `Badge` with Grid82's 11 named tints (`blue`, `green`, `amber`, `yellow`, `orange`, `red`, `pink`, `violet`, `indigo`, `gray`, `teal`), `Code`, `Snippet`, `Avatar`.
- **Inputs and forms.** `Input`, `Textarea`, `Checkbox`, `Switch`, `Slider`, `OptionSelect`, `Select`, `MultiSelect`, `Combobox`, `Field`, `FieldLabel`.
- **Surfaces and overlays.** `Card`, `Item` / `ItemGroup`, `Tabs`, `Accordion`, `Collapsible`, `Dialog` (`sm` 420 / `md` 560 / `lg` 880), `Sheet`, `Popover`, `Menu`, `Tooltip`, `Table`, `SkeletonRows`, `Alert`, `InfoTip`.

## Charts and spreadsheet imports

- **Charts (`@grid82/charts`).** `BarChart`, `LineChart`, `AreaChart`, and `PieChart` inherit your app's theme colors, axes, and tooltips automatically:

```tsx
import { BarChart } from "@grid82/charts";

<BarChart
  data={rows}
  x="month"
  series={[{ key: "revenue", label: "Revenue", format: "currency" }]}
/>
```

- **Spreadsheets (`@grid82/sheets`).** Drop in `<ImportDialog tableId="..." />` for standard append-only CSV/TSV/XLSX imports, or compose `readSheet(file)`, `suggestMapping(...)`, `coerceRows(...)`, and `matchRows(...)` (which parses files inside the browser frame without uploading raw spreadsheets) for custom upsert workflows.

## Visual rules enforced by the compiler

The page compiler rejects unknown Tailwind classes (`bg-indigo-500`, `text-sm`) and warns on hardcoded hex colors or second fonts. Use Grid82's semantic tokens (`bg-card`, `bg-muted`, `text-foreground`, `text-muted-foreground`, `border-border`) and six typography scales (`text-label` 14px, `text-body` 15px, `text-lead` 16px, `text-title` 18px, `text-head` 22px, `text-display` 26px), with sentence-case headings and `tabular` right-aligned numbers.
