Layout
Layout
The optional layout key in resource.json lets you declare an explicit layout for the generated form, view, and table instead of the default source-order grid.
When layout is absent, the view is built exactly as before β one control per visible column in a 12-column GridLayout. Backward-compatible and additive: no schemaVersion bump, no migration needed.
A layout is the full list
If
layout.<ctx>is defined, it is the only source of truth for presentation in that context. Column settings are fallbacks used only when that context has no layout.
Each context (form, view, table) is decided on its own: a resource with only layout.form still builds its table and view from the column flags.
With layout.<ctx> | Rule |
|---|---|
| Columns listed in the layout | Rendered, in layout order β even with hiddenIn<Ctx>: true |
| Columns not listed | Not rendered (nothing is appended) |
hiddenIn<Ctx> | Ignored for that context |
Order, colspan, rowspan, width, hideLabel, readonly, label | Set on the item; the column label is the default |
| Unknown or duplicate ids | Validation error |
Not overridden by a layout (data rules, apply everywhere): id, column, idField, type, required, unique, creatable, updatable, enum, displayKey, sortId. A layout decides what is shown and how, not what is valid or writable.
Without a layout, a context shows the columns not hidden by hiddenIn<Ctx>, in declaration order, full width. Placement keys on columns (position, hideLabel, fieldInput.position, fieldInput.options.colspan/width/β¦) are no longer accepted β see the migration guide section Column presentation β layout items.
Common mistake
Setting hiddenInForm while layout.form exists does nothing. Remove the column from layout.form.items instead.
Shape
{
"layout": {
"form": {
...
},
"view": {
...
},
"table": {
...
}
}
}Each of form, view, and table is optional. Only the keys you declare are affected.
Layout nodes
A node is a container. It has a type (the layout kind) and an items list whose entries are rendered in declared order.
{
type ? : "grid" | "vertical" | "horizontal" | "collapse" | "group",
columns ? : number, // grid column count (default 12)
title ? : string, // heading for collapse/group
titleKey ? : string, // resolve heading from a field value at render time
colspan ? : number, // this node's span inside its parent grid (1β12)
rowspan ? : number, // CSS row-span of this node inside its parent grid
label ? : string,
items ? : [...] // entries in declared order (see "Items" below)
}A node with no type defaults to "grid".
Items
Every entry in an items array is one of four kinds, detected by its shape:
| Shape | Kind | Rendered as |
|---|---|---|
"fieldName" (string) | Field id | The field's default renderer |
{ "id": "fieldName", ... } | Field control (has id) | Field renderer with overrides |
{ "component": "MyComponent", ... } | Component (has component) | Custom Vue component from customComponents |
| Any other object | Nested node | Recursive layout container |
Detection uses only the presence of id or component β not type, because field controls also have a type (input override, e.g. "textarea").
Order is preserved. Items render exactly in the order declared β you can interleave fields, collapse sections, and components freely.
Field control options
{
"id"
:
"fieldName",
"colspan"
:
6, // override column span (1β12)
"rowspan"
:
2, // override row span
"width"
:
"w-40", // named size (xs/sm/md/lg/xl/full) or raw Tailwind class
"label"
:
"Custom label",
"hideLabel"
:
true,
"type"
:
"textarea", // override input type for this placement
"options"
:
{
"minHeight"
:
"8rem"
} // merged over fieldInput.options
}Component item options
{
"component": "RecordSummary",
"colspan": 6, // optional, 1β12 (default 12)
"label": "Summary", // optional
"props": { "compact": true } // optional, static props for the component
}Component references resolve by name from the app's customComponents registry (registered via useCrouton()).
In layout.form / layout.view the component receives these props:
| Prop | Value |
|---|---|
data | The record being edited or viewed (current form values) |
readonly | true in the detail view / readonly forms |
schema | JSON Schema of the form |
uischema | The component element (options.component, options.props) |
β¦props | Every key of the item's props, spread as its own prop |
Examples
Grid with colspan
"form": {
"type": "grid",
"columns": 12,
"items": [
{
"id": "label",
"colspan": 3
},
{
"id": "title",
"colspan": 9
},
"description"
]
}Collapse section
"form": {
"items": [
"title",
"body",
{
"type": "collapse",
"title": "Metadata",
"items": [
"createdAt",
"updatedAt"
]
}
]
}Group section (non-collapsible)
"form": {
"items": [
{
"type": "group",
"title": "Author",
"items": [
"authorName",
"authorEmail"
]
}
]
}Interleaved fields and sections
Because items render in declared order, you can mix fields and containers freely:
"form": {
"type": "grid",
"columns": 12,
"items": [
{
"id": "title",
"colspan": 9
},
{
"id": "status",
"colspan": 3
},
{
"type": "collapse",
"title": "Advanced",
"items": [
"slug",
"publishedAt"
]
},
{
"id": "body"
}
]
}The collapse renders between status and body β not at the end.
Rowspan
"form": {
"type": "grid",
"columns": 12,
"items": [
{
"id": "body",
"colspan": 6,
"rowspan": 2
},
{
"id": "title",
"colspan": 6
},
{
"id": "status",
"colspan": 6
}
]
}Control overrides
"form": {
"items": [
{
"id": "title",
"label": "Custom Title Label",
"colspan": 6
},
{
"id": "body",
"options": {
"minHeight": "6rem"
}
},
{
"id": "status",
"hideLabel": true
}
]
}Nested sections
"form": {
"type": "grid",
"columns": 12,
"items": [
{
"id": "title",
"colspan": 6
},
{
"id": "status",
"colspan": 6
},
{
"type": "collapse",
"title": "Author details",
"items": [
{
"type": "grid",
"columns": 12,
"items": [
{
"id": "authorName",
"colspan": 6
},
{
"id": "authorEmail",
"colspan": 6
}
]
}
]
}
]
}Table layout (layout.table)
layout.table is either a table node (flat) or a wrapper containing exactly one table node somewhere in the tree.
Table node
The table node carries all table-specific settings:
"table": {
"title": "Books",
"items": [
{
"id": "title",
"sortable": true,
"defaultSort": true
},
{
"id": "status",
"sortable": true,
"showWhen": {
"field": "active",
"eq": true
}
},
{
"id": "authorId",
"type": "select",
"options": {
"values": []
}
},
"createdAt",
"updatedAt"
],
"rowActions": [
{
"id": "approve",
"label": "Approve",
"type": "post"
}
],
"tableActions": [
{
"id": "exportCsv",
"label": "Export CSV",
"type": "post"
}
]
}| Field | Description |
|---|---|
items[] | Column order + per-column overrides. Entries are field ids (strings) or field controls (objects with id). No nested nodes β the table is flat. |
rowActions | Per-record actions (receive the record id). |
tableActions | Global toolbar actions (no record id). |
title / label | Heading rendered above the table. title wins over label. |
Per-column table item options
| Field | Type | Description |
|---|---|---|
sortable | boolean | Enable sort toggle on this column header. |
defaultSort | true | "asc" | "desc" | Initial sort column and direction. true = "asc". At most one column. |
width | named ("xs" β "xl") or CSS value | Column width. |
minWidth / maxWidth | CSS value | Width constraints. |
align | "left" | "center" | "right" | Cell text alignment. Number columns default to "right". |
truncate | boolean | number | true = single-line ellipsis; number = max lines before clamp. |
pin | "left" | "right" | Sticky column. |
visible | boolean | false = hidden by default (still in the schema; no column chooser yet). |
headerTooltip | string | Tooltip text on the column header. |
showWhen | { field, eq?, neq?, exists?, notExists? } | Show column when condition matches. |
hideWhen | Same shape | Hide column when condition matches. |
disabledWhen | Same shape | Disable column when condition matches. |
type + options override the cell renderer for this column in the table only.
Tips
colspan, rowspan, and hideLabel are form-layout options and have no effect on table items β they produce a validation error if set.
Table node options
Beyond items, the table node accepts presentation options:
| Field | Type | Description |
|---|---|---|
pageSize | number | Default page size (default 20). Frontend hint; server still caps it. |
pageSizes | number[] | Page size selector options (e.g. [20, 50, 100]). |
density | "normal" | "compact" | Row height. |
selectable | boolean | Show row checkboxes for multi-select. |
rowClick | "view" | "edit" | "none" | What happens when a row is clicked. |
emptyText | string | Message shown when there are no rows. |
"table": {
"pageSize": 50,
"pageSizes": [
20,
50,
100
],
"density": "compact",
"rowClick": "view",
"emptyText": "No books yet",
"items": [
{
"id": "title",
"sortable": true,
"defaultSort": "desc",
"width": "md",
"truncate": 2
},
{
"id": "price",
"align": "right",
"width": "xs"
},
{
"id": "status",
"pin": "left"
},
{
"id": "internalRef",
"visible": false
}
]
}Table column order
"table": {
"items": [
"title",
"status",
"createdAt"
]
}Columns present in the table but not listed here are appended in their original order.
Wrapper layout
A layout.table with an outer container type (not "table") wraps the table. Put component items alongside the inner { "type": "table", ... } node:
"table": {
"type": "grid",
"columns": 12,
"items": [
{
"component": "CreateByIsbn",
"colspan": 12
},
{
"type": "table",
"title": "Books",
"items": [
"title",
"author",
{
"id": "isbn",
"sortable": true
},
"publishedYear",
"status"
],
"tableActions": [
{
"id": "searchOpenLibrary",
"type": "link",
"href": "https://openlibrary.org/search",
"label": "Search Open Library"
}
],
"rowActions": [
{
"id": "openOnOpenLibrary",
"type": "link",
"href": "https://openlibrary.org/isbn/{isbn}",
"label": "Open on Open Library",
"condition": {
"field": "isbn",
"op": "exists"
}
}
]
}
]
}All table settings (rowActions, tableActions, title) go on the table node, not the wrapper.
Wrappers can nest arbitrarily:
"table": {
"type": "vertical",
"items": [
{
"type": "horizontal",
"items": [
{
"component": "CreateByIsbn"
},
{
"component": "ImportCsv"
}
]
},
{
"type": "collapse",
"title": "Stats",
"items": [
{
"component": "BookStats"
}
]
},
{
"type": "table",
"items": [
"title",
"author"
]
}
]
}Tips
Use the wrapper pattern when you need a custom action component alongside the table β for example a barcode scanner that creates a record directly. Each component receives a resource prop (the UseResource instance for the current table).
How a record opens (layout.<form|view>.container)
The container key on layout.form and layout.view controls how a record opens when a row is clicked.
"layout": {
"form": {
"container": {
"mode": "modal",
"size": "xl"
},
"items": [
...
]
},
"view": {
"container": {
"mode": "page"
}
},
"table": {
"rowClick": "view",
"items": [
...
]
}
}| Field | Values | Default | Description |
|---|---|---|---|
container.mode | "modal" | "page" | "modal" | How the record opens |
container.size | "xs" | "sm" | "lg" | "xl" | "sm" | Modal width (ignored for "page" mode) |
layout.table.rowClick decides what opens ("view", "edit", or "none"); the container decides how.
view.component replaces the whole detail view with a custom Vue component:
"view": {
"component": "BookDetail"
}Migration
The old root keys display and modalSize are removed.
Missing / extra columns
- An item id that doesn't match a column β validation error (the file fails to load).
- The same id twice in one context β validation error.
- Columns not referenced anywhere in the layout β not rendered. A
required+creatablecolumn missing fromlayout.formlogs a warning: create will fail unless a hook or default fills it.
Playground
Edit the layout JSON live and see the result update: