Record grid
Records as a sheet, edited in place: arrows, Enter or F2, type to replace, Escape, Tab, Delete.
import { RecordGrid } from "@forgeron/ui";name | stock | organic |
|---|---|---|
| Brie de Meaux | 42 | Yes |
| Comté 18 mois | 7 | No |
| Tomme de Savoie | Yes |
import { RecordGrid, type CellValue, type DataField, type DataRecord } from "@forgeron/ui";
import { useState } from "react";
const fields: DataField[] = [
{ id: "name", name: "name", type: "text", required: true },
{ id: "stock", name: "stock", type: "number", decimals: 0 },
{ id: "organic", name: "organic", type: "boolean" },
];
export default function Default() {
const [records, setRecords] = useState<DataRecord[]>([
{ id: "1", values: { name: "Brie de Meaux", stock: 42, organic: true } },
{ id: "2", values: { name: "Comté 18 mois", stock: 7, organic: false } },
{ id: "3", values: { name: "Tomme de Savoie", stock: null, organic: true } },
]);
const change = (id: string, field: string, value: CellValue) =>
setRecords((all) =>
all.map((r) => (r.id === id ? { ...r, values: { ...r.values, [field]: value } } : r)),
);
return (
<div style={{ width: 380 }}>
<RecordGrid
label="products"
fields={fields}
records={records}
onChange={change}
widths={{ name: 168 }}
/>
</div>
);
}4 records
| 1 | Winter cheese boards | Won | 12480.00 | Fromagerie Roy | 2026-11-04 | Yes | B2BRetail | camille@roy.fr | quote-1042.pdf | ||
| 2 | Refrigerated transport, Q1 | Quote | 8900.50 | Garnier Transports | 2026-12-15 | No | B2B | hugo@garnier.fr | |||
| 3 | Export to Geneva | Lead | Petit & Fils | No | Export | ||||||
| 4 | Supermarket shelf space | Lost | 3200.00 | Martin Distribution | 2026-10-01 | No | Retail | lea@martin.fr |
// A table editor: every field type, rows to select and open, a + to add a record or a field, the
// headers sort. Click a cell, then use the keyboard: arrows, Enter or F2, type to replace, Escape,
// Tab, Delete, Space on a checkbox, Shift+Enter opens the record.
import {
Drawer,
RecordForm,
RecordGrid,
type CellValue,
type DataField,
type DataRecord,
type RecordGridSort,
} from "@forgeron/ui";
import { useState } from "react";
const fields: DataField[] = [
{ id: "id", name: "id", type: "number", primary: true, decimals: 0 },
{ id: "name", name: "name", type: "text", required: true },
{
id: "stage",
name: "stage",
type: "select",
choices: [
{ value: "lead", label: "Lead", color: "var(--ink-dim)" },
{ value: "quote", label: "Quote", color: "var(--warning)" },
{ value: "won", label: "Won", color: "var(--success)" },
{ value: "lost", label: "Lost", color: "var(--danger)" },
],
},
{ id: "amount", name: "amount", type: "number", decimals: 2 },
{ id: "company", name: "company_id", type: "relation", relation: { table: "companies" } },
{ id: "close", name: "close_date", type: "date" },
{ id: "signed", name: "signed", type: "boolean" },
{
id: "tags",
name: "tags",
type: "multiSelect",
choices: [
{ value: "b2b", label: "B2B", color: "var(--accent)" },
{ value: "export", label: "Export", color: "var(--success)" },
{ value: "retail", label: "Retail", color: "var(--ink-dim)" },
],
},
{ id: "contact", name: "contact_email", type: "email" },
{ id: "files", name: "attachments", type: "file" },
];
const relations = {
companies: [
{ id: "c-104", label: "Fromagerie Roy", hint: "Lyon" },
{ id: "c-212", label: "Garnier Transports", hint: "Grenoble" },
{ id: "c-318", label: "Petit & Fils", hint: "Annecy" },
{ id: "c-402", label: "Martin Distribution", hint: "Chambéry" },
],
};
const seed: DataRecord[] = [
{
id: "1",
values: {
id: 1,
name: "Winter cheese boards",
stage: "won",
amount: 12480,
company: ["c-104"],
close: "2026-11-04",
signed: true,
tags: ["b2b", "retail"],
contact: "camille@roy.fr",
files: ["quote-1042.pdf"],
},
},
{
id: "2",
values: {
id: 2,
name: "Refrigerated transport, Q1",
stage: "quote",
amount: 8900.5,
company: ["c-212"],
close: "2026-12-15",
signed: false,
tags: ["b2b"],
contact: "hugo@garnier.fr",
files: null,
},
},
{
id: "3",
values: {
id: 3,
name: "Export to Geneva",
stage: "lead",
amount: null,
company: ["c-318"],
close: null,
signed: false,
tags: ["export"],
contact: null,
files: null,
},
},
{
id: "4",
values: {
id: 4,
name: "Supermarket shelf space",
stage: "lost",
amount: 3200,
company: ["c-402"],
close: "2026-10-01",
signed: false,
tags: ["retail"],
contact: "lea@martin.fr",
files: null,
},
},
];
const compare = (a: CellValue, b: CellValue) => {
if (a === b) return 0;
if (a === null) return 1;
if (b === null) return -1;
return String(a).localeCompare(String(b), "en", { numeric: true });
};
export default function Spreadsheet() {
const [records, setRecords] = useState(seed);
const [selection, setSelection] = useState<string[]>([]);
const [sort, setSort] = useState<RecordGridSort | null>(null);
const [open, setOpen] = useState<string | null>(null);
const change = (id: string, field: string, value: CellValue) =>
setRecords((all) =>
all.map((r) => (r.id === id ? { ...r, values: { ...r.values, [field]: value } } : r)),
);
const shown = sort
? [...records].sort(
(a, b) =>
compare(a.values[sort.field] ?? null, b.values[sort.field] ?? null) *
(sort.direction === "asc" ? 1 : -1),
)
: records;
const add = () => {
const id = String(Math.max(...records.map((r) => Number(r.id))) + 1);
setRecords([...records, { id, values: { id: Number(id), name: "New deal" } }]);
};
const record = records.find((r) => r.id === open);
return (
<div style={{ display: "flex", gap: 12, width: "100%", alignItems: "flex-start" }}>
<div style={{ flex: 1, minWidth: 0, display: "grid", gap: 8 }}>
<span style={{ font: "400 12px/16px var(--font-mono)", color: "var(--ink-muted)" }}>
{selection.length ? `${selection.length} selected` : `${records.length} records`}
</span>
<RecordGrid
label="deals"
fields={fields}
records={shown}
relations={relations}
onChange={change}
selectable
selection={selection}
onSelectionChange={setSelection}
onOpenRecord={setOpen}
onAddRecord={add}
onAddField={() => {}}
sort={sort}
onSortChange={setSort}
fieldMenu={(f) => [
{ id: "edit", label: `Edit ${f.name}` },
{ id: "hide", label: "Hide the field" },
]}
/>
</div>
{record ? (
<Drawer
title={`deals.${record.id}`}
description="Saved when you press Save."
onClose={() => setOpen(null)}
>
<RecordForm
key={record.id}
mode="edit"
fields={fields}
defaultValue={record.values}
relations={relations}
onCancel={() => setOpen(null)}
onSubmit={(values) => {
setRecords((all) => all.map((r) => (r.id === record.id ? { ...r, values } : r)));
setOpen(null);
}}
/>
</Drawer>
) : null}
</div>
);
}id | partner_id | amount_total | state | synced_at |
|---|---|---|---|---|
| INV/2026/0412 | 1042 | 1840.00 | posted | 2026-11-18 09:15 |
| INV/2026/0413 | 2210 | 312.40 | draft | NULL |
import { RecordGrid, type DataField } from "@forgeron/ui";
const fields: DataField[] = [
{ id: "id", name: "id", type: "text", primary: true },
{ id: "partner", name: "partner_id", type: "number", decimals: 0 },
{ id: "total", name: "amount_total", type: "number", decimals: 2 },
{ id: "state", name: "state", type: "text" },
{ id: "synced", name: "synced_at", type: "datetime" },
];
export default function ReadOnly() {
return (
<div style={{ width: "100%" }}>
<RecordGrid
label="odoo.account_move"
fields={fields}
showNull
records={[
{
id: "INV/2026/0412",
values: {
id: "INV/2026/0412",
partner: 1042,
total: 1840,
state: "posted",
synced: "2026-11-18 09:15",
},
},
{
id: "INV/2026/0413",
values: {
id: "INV/2026/0413",
partner: 2210,
total: 312.4,
state: "draft",
synced: null,
},
},
]}
/>
</div>
);
}API → Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Names the grid: the table name. |
fields | DataField[] | — | { id, name, type, primary?, required?, unique?, readOnly?, defaultValue?, description?, choices?, relation?: { table, multiple? }, decimals? }. |
records | { id, values: Record<fieldId, CellValue> }[] | — | The rows. A list type (multi-select, relation, file) holds a string[]. |
relations | Record<table, { id, label, hint? }[]> | — | The records relation fields can point at, by table: their labels and the picker. |
onChange | (recordId, fieldId, value) => void | — | Turns editing on. A typed value goes through parseValue: a wrong one stays in the cell with its problem. |
selectable | boolean | false | A checkbox per row and in the header; Shift+Space toggles the current row. |
selection / defaultSelection | string[] | — | The selected record ids. Controlled or not. |
onSelectionChange | (ids: string[]) => void | — | When a box is ticked. |
onOpenRecord | (id) => void | — | An expand button per row, and Shift+Enter: open it in a Drawer with RecordForm. |
onAddRecord | () => void | — | A New record row at the end. |
onAddField | () => void | — | A + after the last column. |
sort / onSortChange | { field, direction: "asc" | "desc" } | null | — | Headers become buttons that cycle ascending, descending, none. |
fieldMenu / onFieldAction | (field) => ActionMenuEntry[] | — | The actions of a column, behind a ⋯ in its header. |
active / defaultActive | { record, field } | null | — | The current cell. Controlled or not, with onActiveChange. |
widths | Record<fieldId, number> | — | Column widths in px; by type otherwise. |
showNull | boolean | false | Writes NULL in empty cells, as a database editor does. |
markEdited | boolean | true | An ember corner on the cells changed since the grid was shown. |
empty | ReactNode | "No records yet" | Shown with no record. |
className | string | — | Extra classes. |