Columns
Columns
columns is a map keyed by column id; the key becomes the column's id:
{
"columns": {
"id": { "idField": true, "hiddenInForm": true },
"title": { "label": "Title" }
}
}Unknown keys inside a column fail validation, so a typo like "lable" is reported instead of silently ignored.
Column options:
| Option | Description |
|---|---|
idField | Marks the id column |
type | Data type β a shorthand ("string", "integer", "boolean", "date", β¦) or a JSON Schema fragment for nested shapes. Optional on a prisma resource (derived from the Zod model); required on every column of a kind: "custom" resource, see Custom resources |
label | Default display label (forms, table header, lookups, filters). Override it per context with a layout item label; hide it with a layout item hideLabel |
hiddenInTable / hiddenInForm / hiddenInView | Visibility per context, used only when that context has no layout.<ctx>.items β they are the fallback that builds the layout. As soon as layout.<ctx> lists field items, those items are the full list: only listed columns render and these flags are ignored. On a oneToMany relation column, hiddenInTable (when acting as the table fallback) also drops it from the _count subquery findAll issues |
creatable / updatable | Whether the field is written on create/update |
required | Whether the form demands a value. Overrides the Zod model in either direction on a prisma resource (true adds, false removes, omitted defers to the model); the only way to mark a field required on a kind: "custom" resource. Ignored on the id column and on fields that are neither creatable nor updatable |
displayKey | Nested field to display (e.g. author.name) |
showInLookup (deprecated) | Use lookup.labels at the resource root instead. Sets the display label when this resource appears as an autocomplete option in another resource. Does not affect ?q= search. |
unique | Validate the value is unique: true, or { scope, caseInsensitive, message }. Checks as-you-type and maps a DB unique violation to this field. Needs a matching @unique constraint. See Unique fields |
column | Source column name when it differs from the key/id (defaults to id) |
enum | Name of a shared enum in crouton.enums.json; its { value, label }[] is injected into fieldInput.options.values. Combined with a local fieldInput.options.values list it restricts the enum for that screen (plain string entries resolve their label from the enum). Labels for values outside the restriction still resolve via options.displayValues (loader-written), and rows carrying such a value cannot be edited from the screen β the table's edit button is hidden for them |
extend | Path to another resource.json whose columns are expanded as virtual sub-columns under this key (with a per-sub-column columns override map) |
fieldInput | Form control configuration, see below |
Moved to layout.table
The following column-level options are deprecated and will be removed. Use layout.table instead:
sortableβlayout.table.items[{ id, sortable }]defaultSortβlayout.table.defaultSort({ field: "colId", sortDir: "asc" | "desc" })searchableβoperations.findAll.search: ["colId"]filterableβoperations.findAll.filter: ["colId"]showWhen/hideWhen/disabledWhenβlayout.table.items[{ id, showWhen, ... }]fieldTableβlayout.table.items[{ id, type, options }]
See Layout β Table layout and migrate-to-next-alpha.md for migration details.
Free-text search (?q=)
Declare which columns are included in free-text search via operations.findAll.search:
{
"operations": {
"findAll": {
"search": [
"title",
"authorId"
]
}
}
}- Multiple entries are ORed together:
?q=tolkienmatches books whosetitlecontains "tolkien" OR whose author name contains "tolkien". manyToOnerelation columns (e.g.authorId) automatically resolve to the related resource's first visible display field (e.g.author.name), so you never search against a raw foreign key string.showInLookupis a separate concern β it controls the label shown when this resource appears as an autocomplete option somewhere else. Do not use it to drive?q=search; useoperations.findAll.searchinstead.- Default: when
findAll: trueand no explicitsearchis declared, all simple (non-id, non-relation, non-date) columns are searched.
Nested object and array columns
A column's type may be a full JSON Schema fragment, which is how you describe a value that is not a scalar:
{
"metadata": {
"displayKey": "name",
"type": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"tags": {
"type": {
"type": "array",
"items": {
"type": "string"
}
}
}
}An object column renders as a nested group of controls in the form, and β when it has a displayKey β as a single-value record cell in the table.
Field inputs (fieldInput)
fieldInput selects and configures the form control:
{
"column": "summary",
"fieldInput": {
"type": "textarea",
"options": {
"placeholder": "Short summary"
}
}
}See Field input types for the full list of types and their options.
Placement lives in the layout
A column describes the data and its input. Order, colspan, rowspan, width, hideLabel, readonly and per-context labels go on layout items β columns[id].position, hideLabel, fieldInput.position and fieldInput.options.{colspan,rowspan,width,hideLabel,readonly,label} fail validation. Without a layout, a context renders its visible columns in the order they are declared.
defaultValue β pre-filling the create form
Set fieldInput.defaultValue to pre-fill a field when the user opens a blank create form. The value is applied at form-open time, not persisted until the user saves.
{
"status": {
"fieldInput": {
"type": "select",
"defaultValue": "draft"
}
}
}Dynamic default tokens
| Token | Resolves to |
|---|---|
"$now" | Current datetime as an ISO 8601 string |
"$today" | Current date as an ISO 8601 date string ("2025-03-14") |
"$user" | Current user object (requires defaults in CroutonPlugin config) |
Using $user requires passing the current user when setting up the plugin:
app.use(
CroutonPlugin(api, {
defaults: {
'$user': { id: currentUser.id, name: currentUser.name },
},
}),
);Setting defaults at runtime using useCrouton().setDefault():
const crouton = useCrouton();
onMounted(async () => {
const user = await fetchCurrentUser();
crouton.setDefault('$user', user);
});Defaults also apply on the server when a record is created: literal values and
$now/$todaybecome the Zod default for an omitted field, so a required column can be satisfied by itsdefaultValue.$useris not resolved server-side (there is no user context during validation), so a$userdefault cannot satisfy a required field at the API β use abeforeWritehook for that. Defaults never affect existing records loaded for editing.
Field variants β per-context overrides
A single fieldInput drives the form, the read-only view, and the table cell. To render differently in a specific context, use layout item overrides:
- form β
fieldInput - view β
fieldInput(override per-column vialayout.view.items[{ id, type, options }]) - table β
type/optionson thelayout.table.items[]entry, falling back tofieldInput
{
"columns": {
"author": {
"label": "Author",
"displayKey": "name",
"relation": {
"resource": "./author/resource.json"
},
"fieldInput": {
"options": {
"display": "autocomplete",
"displayKey": "name"
}
}
}
},
"layout": {
"view": {
"items": [
{
"id": "author",
"options": {
"display": "link"
}
}
]
},
"table": {
"items": [
{
"id": "author",
"options": {
"displayKey": "shortName"
}
}
]
}
}
}The edit form renders an autocomplete, the read-only view renders a link, and the table cell uses shortName.
Custom table cell renderer
Add customComponent to the table layout item's options to override the cell with a custom Vue component:
{
"layout": {
"table": {
"items": [
{
"id": "section_number",
"options": {
"customComponent": "moveUpDown"
}
}
]
}
}
}The custom cell component receives data (full row object), value (cell value), column, and options as props. See Custom renderers for how to register the component.
Computed columns
Read-only columns derived from a raw SQL subquery at query time. Add a computed object to the column definition:
{
"columns": {
"chapter_count": {
"label": "Chapters",
"computed": {
"sql": "(SELECT count(*) FROM chapter c WHERE c.book_id = main.id)",
"type": "number"
}
}
}
}| Field | Type | Description |
|---|---|---|
sql | string | Raw SQL subquery. Use main as the alias for the parent table row. |
type | string | Cast type for the result: "number" (default), "string", or "boolean". |
All standard column fields (label, hiddenInTable, hiddenInView, fieldInput, β¦) are valid alongside computed. When a context declares a layout, list the computed column's id in layout.table.items / layout.view.items to place it there (it is hidden otherwise); with no layout it follows hiddenInTable / hiddenInView and renders after the regular columns.
Warning
Computed columns are not available on kind: "custom" resources β they run raw SQL against a real table. Compute the value in findAll instead.
Deprecated: calculatedColumns
The top-level calculatedColumns array is removed β computed columns live on columns[id].computed. Legacy top-level entries no longer accept hiddenInTable / hiddenInView; without an explicit layout such a column is always rendered.
Includes
Eagerly load relations with the list/detail queries. Declare them per operation so findAll and findOne can differ.
Dot-path strings (recommended for simple nesting)
Use "a.b" shorthand instead of the verbose object form when you don't need orderBy:
{
"operations": {
"findAll": {
"include": [
"author",
"chapters.sections"
]
}
}
}Multiple dot-path entries for the same top-level relation are deep-merged:
"include": ["a.b", "a.c"]
// β { a: { include: { b: true, c: true } } }Mix dot paths and object form freely β they merge on the same relation:
"include": [
"chapters.sections",
{ "relation": "chapters", "orderBy": { "position": "asc" } }
]
// β chapters included with sections nested + orderBy appliedObject form (when you need options)
{
"operations": {
"findAll": {
"include": [
"author",
{
"relation": "chapters",
"orderBy": { "position": "asc" },
"include": ["sections"]
}
]
}
}
}When findOne.include is absent, crouton falls back to findAll.include.
| Field | Type | Description |
|---|---|---|
relation | string | Prisma relation field name |
orderBy | object | Optional sort: { field: 'asc' | 'desc' } for included records |
include | array | Nested includes (string, dot-path, or object) |
When a relation column has a sort option (see Relations), the loader automatically injects the corresponding orderBy into the include clause β no manual configuration needed.
?include= is limited to relation columns the table layout renders (via layout.table.items); without a table layout it falls back to the hiddenInTable column flag. A relation the table never shows cannot be included.
Deprecated: root include
The top-level include field is removed. Move it to operations.findAll.include / operations.findOne.include.