The layout spec
A layout is JSON: a flat map of elements and the key of the one at the root.
{
"root": "page",
"elements": {
"page": {
"type": "Stack",
"props": { "direction": "vertical", "gap": "md" },
"children": ["hero", "stats"]
},
"hero": {
"type": "ImageHeader",
"props": { "src": { "$state": "/image" }, "title": { "$state": "/name" } },
"children": []
},
"stats": {
"type": "StatGrid",
"props": {
"items": [
["Strength", { "$state": "/strength" }],
["Dexterity", { "$state": "/dexterity" }]
],
"cols": 2
},
"children": []
}
}
}
Elements
| Key | What it is |
|---|---|
root |
The key of the element at the top. |
elements |
Every element, by key. There is no nesting: the tree is made only by children. |
type |
The component's name, exactly as the component reference writes it. |
props |
The component's props. Required on every element, even when empty: "props": {}. |
children |
The keys of the elements inside it, in order. Every key must exist in elements, or that part is missing. |
visible |
Optional. A condition that hides the element when false. |
repeat |
Optional. Renders the children once per item of an array. |
sections |
Top level, optional. Named fragments mounted by Include or SectionSwitch. |
Keep element keys readable: hero-image, stats-section,
backstory-text.
Data binding
A file's content is the layout's state. Bind a prop to a field with
{ "$state": "/fieldName" }:
{ "text": { "$state": "/name" } }
{ "value": { "$state": "/stats/strength" } }
A nested field is a path: /stats/strength reads stats.strength. The
paths you can bind are the type's schema fields, plus these:
| Path | What it holds |
|---|---|
/title |
The file's name (the same as /name). |
/description |
The file's description. |
/image |
The file's main picture. Image components read its URL, focal point and generation state themselves. |
/createdAt, /updatedAt |
When the file was made and last changed. |
/_<field>Entries |
For each object field, its [key, value] pairs: useful for a stat grid or table when the keys aren't fixed. |
Computed fields are worked out into the state too, and bind like any other field. They show read-only.
Visibility
visible hides an element when its condition is false. A "has a value"
condition on a field the element or anything inside it shows
("visible": {"$state": "/patronus"} on the Patronus row, or on a Card
holding a Markdown of /notes) is ignored: an empty field stays on the
sheet so players can fill it in. Gate on another field (a toggle, a
class) instead.
{
"type": "Image",
"props": { "src": { "$state": "/portrait" }, "alt": "Portrait" },
"visible": { "$state": "/showPortrait" },
"children": []
}
| Condition | Form |
|---|---|
| Has a value | { "$state": "/field" } |
| Equal, not equal | { "$state": "/field", "eq": "value" }, "neq" |
| Compare | { "$state": "/level", "gte": 3 }, also gt, lt, lte. The value may be a number or { "$state": "/otherField" }. |
| Not | add "not": true to any condition |
| All | { "$and": [a, b] }, or a plain array [a, b] |
| Any | { "$or": [a, b] } |
Use one comparison per condition. eq and neq compare exactly: a
number stored as text doesn't equal a number.
When the "has a value" form tests a field the element or anything inside
it shows (like the image above), the editor keeps the element on the page so the empty
field can still be filled in. Every other condition hides the element
everywhere, so use a different field (a toggle such as /offersGear) for
a section that should really disappear.
ImageHeader needs no condition: with no picture it shows a gradient.
Repeats
Any element can render its children once per item of an array:
{
"trackers-list": {
"type": "Stack",
"props": { "direction": "vertical", "gap": "sm" },
"repeat": { "statePath": "/trackers", "key": "key" },
"children": ["tracker-row"]
},
"tracker-row": {
"type": "Dots",
"props": {
"label": { "$item": "label" },
"value": { "$item": "current" },
"max": { "$item": "max" }
},
"visible": [{ "$item": "style", "eq": "dots" }],
"children": []
}
}
- Inside the repeat,
{ "$item": "field" }reads a field of the current item and{ "$item": "" }the whole item. Conditions can use$itemand{ "$index": true }, for example to show a row from a level up:{ "$item": "minLevel", "lte": { "$state": "/level" } }. keynames an item field whose value is unique and stable.statePathis a full path. Repeats don't nest: to group (spells by level), repeat over the groups and use a component that lists its own items, such asChecklistorBadgeList.- Editing an
$itemvalue saves it to that item.
Prefer one array with a field that tells items apart (a spells array
with a level) over numbered fields (spells1 … spells9).
Edit paths
A value worked out by a computed field can't be edited, so a control that
repeats over a computed list can't save to its rows. editPath sends the
edit somewhere else: the control still shows the computed value, and an
edit saves to the stored path you name.
This is the pattern for class resources (rage, ki, spell slots): the
maximums live on the class file, the current values in a stored map on
this file, and a computed resources list joins them.
{
"resource-list": {
"type": "Stack",
"props": { "direction": "vertical", "gap": "sm" },
"repeat": { "statePath": "/resources", "key": "key" },
"children": ["resource-row"]
},
"resource-row": {
"type": "Dots",
"props": {
"label": { "$item": "name" },
"value": { "$item": "current" },
"max": { "$item": "maximum" },
"editPath": { "value": "/resourceState/{key}/current" }
},
"children": []
}
}
editPathmaps an editable prop to a full state path.{key}reads that field of the current item, so each row needs a stable slug matching the stored map's keys. The map is keyed by slug, never by row number or display name.- A path with
{placeholders}works only inside a repeat. A path without them works anywhere. When a placeholder can't be filled, the control shows read-only instead of saving somewhere wrong. - The path must end at a stored field. A path on or under a computed field is refused, and the control stays read-only.
- The path doesn't need to exist yet. The first edit creates it.
Dots,Stepper,Progress,TrackBoxes,Clock,ToggleandTexttake an edit path.- The display must read the written value back. The computed list has to
read the same stored path (
current: $self.resourceState?.[r.key]?.current ?? 0), or the edit saves and the sheet never shows it. - A key made only of digits is an array index:
/resourceState/3/currentwrites into an array. Use keys likerageorslots-1.
Outside a repeat, one known resource needs no edit path: bind value to
the stored path (/resourceState/rage/current) and max to a computed
field.
Sections
Blocks that only some files need, such as a subclass's features, go in
named sections. Each section is a small layout of its own, with its own
root and elements, reading the same state:
{
"root": "page",
"elements": {
"page": { "type": "Stack", "props": {}, "children": ["subclass-features"] },
"subclass-features": {
"type": "SectionSwitch",
"props": {
"statePath": "/subclassName",
"cases": [
{ "equals": "The Fiend", "section": "warlock-the-fiend" },
{ "equals": "The Archfey", "section": "warlock-the-archfey" }
],
"default": null
},
"children": []
}
},
"sections": {
"warlock-the-fiend": {
"name": "The Fiend",
"root": "card",
"elements": {
"card": { "type": "Card", "props": { "title": "The Fiend" }, "children": [] }
}
},
"warlock-the-archfey": {
"name": "The Archfey",
"root": "card",
"elements": {
"card": { "type": "Card", "props": { "title": "The Archfey" }, "children": [] }
}
}
}
}
SectionSwitchmounts the section of the first case whose value equals the one atstatePath, ordefaultwhen none does.Include({ "section": "<id>" }) always mounts one section. Give it avisiblecondition for a single optional block.- Sections can't mount other sections. Every section named must exist.
- Adding a subclass means one new section and one new case.
References to other files
Declare a reference in the schema first. The field that holds it names the type it points to:
{
"armor": { "type": "string", "referencedFileTypeSlug": "armor" },
"inventory": {
"type": "array",
"items": {
"type": "object",
"properties": {
"item": { "type": "string", "referencedFileTypeSlug": "item" },
"quantity": { "type": "number" }
}
}
}
}
In content, write the file's slug ("armor": "leather-armor"). Craft
stores the reference itself. Never make up reference ids.
| To show | Use |
|---|---|
| One reference | Select with fileTypeSlug |
| A list of references | FileReferenceGrid with fileTypeSlug, and referenceField when the items are objects |
| A short list of references | BadgeList with fileTypeSlug |
| One reference's value, read-only | ReferenceValue |
| Fields of each file in a list (each teammate's level) | a computed list, $self.team.map(c => ({ name: load(c)?.$name, level: load(c)?.level })), shown in a DataTable |
{
"type": "FileReferenceGrid",
"props": {
"items": { "$state": "/inventory" },
"fileTypeSlug": "item",
"referenceField": "item",
"columns": 4,
"label": "Inventory"
},
"children": []
}
- In a list of objects, the other fields (quantity, equipped) show as badges on each card.
- A single slot can use the grid too:
"items": [{ "$state": "/mainHand" }]with"referenceField": null. - A field that may point to several types lists them all in
fileTypeSlugs(["weapon", "item"]). Picked values are saved as"type/slug". - These components add and remove references themselves. Don't build
your own controls for it.
showAddNew: falsehides adding, andshowAddNewOnHover: falsekeeps the add button visible on desktop.