Craft

Layout components

Each entry below comes from the component catalog that checks layouts, so the names, props and values are exactly what a layout accepts.

Some props work the same everywhere:

  • Any prop can be bound to a field with { "$state": "/field" } instead of a fixed value. The types below are the values it resolves to.
  • Every component takes className, extra Tailwind classes for its outer box (col-span-2, mt-4).
  • Colors (color, bgColor, borderColor, trackColor, labelColor, valueColor, emptyColor) take any CSS color.
  • Background pictures: Stack, Grid and Card take bgImage (an image URL, or a binding to an image field) and bgImageFit. A Tailwind url() class can't work, because the styles are built ahead of time.
  • Aspect ratios are "video" (16:9), "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9) and "ultratall" (9:32).
  • Editable values (value on play-time controls) save when a player changes them, unless the bound field is computed. editPath sends the edit to a stored field instead (see the spec).

PageReferenceGrid still renders in old layouts. Use FileReferenceGrid instead. A script's card has more components of its own; they are covered with scripts.

Structure

Stack

Flex layout container. bgColor sets background color (any CSS color value). bgImage sets a background image URL (children render on top); bgImageFit controls how it fills: "cover" (default, crop to fill), "contain" (fit inside), "tile" / "tile-x" / "tile-y" (repeat at natural size for seamless textures). Use className for extra Tailwind utilities (e.g. col-span-*, mt-4). Set wrap=true to allow line wrapping.

Prop Type Required
direction "horizontal" | "vertical"
gap "xs" | "sm" | "md" | "lg" | "none"
align "start" | "center" | "end" | "stretch"
justify "start" | "center" | "end" | "between" | "around"
wrap boolean
bgColor string
bgImage string
bgImageFit "cover" | "contain" | "tile" | "tile-x" | "tile-y"
rounded "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full"
{
  "type": "Stack",
  "props": {"direction":"vertical","gap":"md"},
  "children": []
}

Grid

CSS grid layout. columns sets equal column count (supports 1-12). bgColor sets background color (any CSS color value). bgImage sets a background image URL (children render on top); bgImageFit controls how it fills: "cover" (default, crop to fill), "contain" (fit inside), "tile" / "tile-x" / "tile-y" (repeat at natural size for seamless textures). Use className for extra Tailwind utilities. Children can use className with col-span-* for responsive multi-column layouts.

Prop Type Required
columns number
gap "xs" | "sm" | "md" | "lg"
bgColor string
bgImage string
bgImageFit "cover" | "contain" | "tile" | "tile-x" | "tile-y"
rounded "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full"
{"type":"Grid","props":{"columns":2,"gap":"md"},"children":[]}

Card

Container card with optional title/description. bgColor and borderColor accept any CSS color value. bgImage sets a background image URL (children render on top); bgImageFit controls how it fills: "cover" (default, crop to fill), "contain" (fit inside), "tile" / "tile-x" / "tile-y" (repeat at natural size for seamless textures). Use className for extra Tailwind utilities (e.g. col-span-*).

Prop Type Required
title string
description string
maxWidth "sm" | "md" | "lg" | "full"
centered boolean
bgColor string
bgImage string
bgImageFit "cover" | "contain" | "tile" | "tile-x" | "tile-y"
borderColor string
rounded "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full"
{
  "type": "Card",
  "props": {"title":"Character Stats","description":null},
  "children": []
}

Separator

Visual separator line

Prop Type Required
orientation "horizontal" | "vertical"

Tabs

Tab navigation. bgColor sets the tab list background color (any CSS color value).

Prop Type Required
tabs ({ label, value })[] yes
defaultValue string
value string
bgColor string
{
  "type": "Tabs",
  "props": {
    "tabs": [
      {"label":"Overview","value":"overview"},
      {"label":"Stats","value":"stats"}
    ],
    "defaultValue": "overview"
  },
  "children": []
}

Children map to tabs by position: the first child is the first tab's panel.

Accordion

Collapsible sections. Items as [{title, content}]. Type 'single' (default) or 'multiple'.

Prop Type Required
items ({ title, content })[] yes
type "single" | "multiple"

Collapsible

Collapsible section with trigger. Children render inside.

Prop Type Required
title string yes
defaultOpen boolean

Table

Data table. columns: header labels. rows: 2D array of cell strings, e.g. [["Alice","admin"],["Bob","user"]]. Set wrapText: true for long descriptions or label/content pairs: headers and cells wrap within the available width, preserve line breaks, and break long words or URLs as needed. Omit or set false to keep single-line cells with horizontal scrolling.

Prop Type Required
columns string[] yes
rows string[][] yes
caption string
wrapText boolean
{
  "type": "Table",
  "props": {"columns":["Name","Role"],"rows":[["Alice","Admin"],["Bob","User"]]},
  "children": []
}

The cells are fixed text. For rows a player edits, use DataTable.

Include

Mounts a named layout section at this position. Sections are reusable fragments stored under the layout's top-level "sections" map ({ "": { name, root, elements } }); combine Include with a "visible" condition to show a section conditionally. Sections cannot include other sections.

Prop Type Required
section string yes
{"type":"Include","props":{"section":"warlock-the-fiend"},"children":[]}

SectionSwitch

Mounts exactly one named layout section based on the value at statePath — the layout-level switch for class/subclass/archetype-specific sheet parts. Each case compares with strict equality; "default" (optional) names a section shown when no case matches. Prefer one SectionSwitch over many per-element visible gates.

Prop Type Required
statePath string yes
cases ({ equals, section })[] yes
default string
{
  "type": "SectionSwitch",
  "props": {
    "statePath": "/subclassName",
    "cases": [
      {"equals":"The Fiend","section":"warlock-the-fiend"},
      {"equals":"The Archfey","section":"warlock-the-archfey"}
    ],
    "default": null
  },
  "children": []
}

Text, images and stats

Heading

Section heading (h1–h4). Use color for custom text color (any CSS color value). Defaults to h2 if level is omitted.

Prop Type Required
text string yes
level "h1" | "h2" | "h3" | "h4"
color string
{
  "type": "Heading",
  "props": {"text":"Character Stats","level":"h3","color":"#ef4444"},
  "children": []
}

Text

Text paragraph with optional variant and custom color. Accepts any CSS color value. Bound text edits inline. editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.

Prop Type Required
text string yes
variant "caption" | "body" | "muted" | "lead" | "code"
color string
editPath Record<string, string>
{
  "type": "Text",
  "props": {"text":"Hello world","color":null},
  "children": []
}

Markdown

Renders markdown text with prose styling. Supports bold, italic, code, links, and lists. Use color for custom text color.

Prop Type Required
content string yes
color string
{
  "type": "Markdown",
  "props": {
    "content": "**Hello** world — supports *markdown* formatting.",
    "color": null
  },
  "children": []
}

Callout

Framed lore/flavor block. variant "quote" (default) renders italic text behind a left accent border with an optional em-dash attribution; "panel" renders a soft filled box with an optional icon and title. icon accepts any text/emoji (e.g. "📜"). color tints the accent and title, bgColor sets the panel background.

Prop Type Required
text string yes
title string
attribution string
icon string
variant "quote" | "panel"
color string
bgColor string
{
  "type": "Callout",
  "props": {
    "text": "Not all those who wander are lost.",
    "title": null,
    "attribution": "Gandalf's letter",
    "icon": null,
    "variant": "quote",
    "color": null,
    "bgColor": null
  },
  "children": []
}

Alert

Alert banner

Prop Type Required
title string yes
message string
type "info" | "success" | "warning" | "error"
{
  "type": "Alert",
  "props": {
    "title": "Note",
    "message": "Your changes have been saved.",
    "type": "success"
  },
  "children": []
}

Image

Image display with configurable size and alignment. size controls max width: sm (200px), md (400px), lg (600px), full (100%); on a script's card they follow the card: sm is a 64px thumbnail, md 160px, lg 320px. align controls horizontal alignment: left, center, right. Defaults to full size, left aligned. aspectRatio crops the image to a fixed ratio: "video" (16:9), "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9), "ultratall" (9:32); omit to keep the natural ratio.

Prop Type Required
src string yes
alt string
size "sm" | "md" | "lg" | "full"
align "left" | "center" | "right"
aspectRatio "video" | "square" | "portrait" | "tall" | "ultrawide" | "ultratall"
stateKey string
{
  "type": "Image",
  "props": {"src":"/image","alt":"A hero portrait","size":"md","align":"center"},
  "children": []
}

ImageHeader

Hero image with optional text overlay. Always renders a gradient fallback when no image is set. aspectRatio defaults to "video" (16:9); also supports "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9) for slim banner rows, and "ultratall" (9:32) for narrow full-height columns.

Prop Type Required
src string
title string
subtitle string
aspectRatio "video" | "square" | "portrait" | "tall" | "ultrawide" | "ultratall"
{
  "type": "ImageHeader",
  "props": {
    "src": "/image",
    "title": "The Dark Forest",
    "subtitle": "A mysterious woodland",
    "aspectRatio": "video"
  },
  "children": []
}

With no picture it shows a gradient, so it needs no visible condition.

Avatar

User avatar with fallback initials

Prop Type Required
src string
name string yes
size "sm" | "md" | "lg"
{"type":"Avatar","props":{"name":"Jane Doe","size":"md"},"children":[]}

Badge

Small inline badge/tag. When color is set (any CSS color value), it overrides the variant with a custom background color and auto-contrasted text.

Prop Type Required
text string yes
variant "default" | "secondary" | "destructive" | "outline"
color string
{
  "type": "Badge",
  "props": {"text":"Active","variant":"default","color":null},
  "children": []
}

List

Plain list of values — traits, features, languages, rumors. items can be strings or objects (map object fields with labelField and descriptionField). variant "bullet" (default) and "numbered" stack items; "inline" flows them on one line joined by separator (default " · "). Bound string lists are editable inline. showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. color sets the item text color.

Prop Type Required
items any[] yes
variant "bullet" | "numbered" | "inline"
labelField string
descriptionField string
separator string
color string
emptyText string
showAddNew boolean
showAddNewOnHover boolean
{
  "type": "List",
  "props": {
    "items": ["Darkvision 60 ft.","Fey Ancestry","Trance"],
    "variant": "bullet",
    "labelField": null,
    "descriptionField": null,
    "separator": null,
    "color": null,
    "emptyText": "None",
    "showAddNew": true,
    "showAddNewOnHover": true
  },
  "children": []
}

FieldList

Vertical list of labeled field/value pairs. Use labelColor and valueColor for custom text colors.

Prop Type Required
items ([string, string])[] yes
labelColor string
valueColor string
{
  "type": "FieldList",
  "props": {
    "items": [["Race","Elf"],["Class","Ranger"],["Alignment","Chaotic Good"]],
    "labelColor": null,
    "valueColor": null
  },
  "children": []
}

StatGrid

Grid of labeled stat values. Each item is a [label, value] tuple. Use color for value text color and bgColor for cell background color.

Prop Type Required
items ([string, string | number])[] yes
cols number
color string
bgColor string
{
  "type": "StatGrid",
  "props": {
    "items": [["Strength",18],["Dexterity",14],["Constitution",16]],
    "cols": 3,
    "color": null,
    "bgColor": null
  },
  "children": []
}

DerivedStatGrid

Grid of labeled stat cells that pair an editable base value with a derived/calculated value, such as ability score plus modifier.

Prop Type Required
items ([string, string | number, string | number])[] yes
baseLabel string
derivedLabel string
cols number
color string
bgColor string
{
  "type": "DerivedStatGrid",
  "props": {
    "items": [["STR",14,2],["DEX",12,1]],
    "baseLabel": "Score",
    "derivedLabel": "Mod",
    "cols": 2,
    "color": null,
    "bgColor": null
  },
  "children": []
}

BadgeList

Wrapped row of badges. Use for tags, abilities, skills, etc. Provide options to show a preset add menu for fixed vocabularies. showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. When color is set, it overrides the variant with a custom background color. For compact reference arrays, provide fileTypeSlug (or fileTypeSlugs when the field targets multiple file types) so the rendered view can resolve names and add references with a picker; fields whose schema already declares reference targets need no slug prop.

Prop Type Required
items string[] yes
options string[]
variant "default" | "secondary" | "outline" | "destructive"
color string
fileTypeSlug string
pageTypeSlug string
fileTypeSlugs string[]
showAddNew boolean
showAddNewOnHover boolean
{
  "type": "BadgeList",
  "props": {
    "items": ["Slash","Block","Charge"],
    "options": ["Slash","Block","Charge","Parry"],
    "variant": "secondary",
    "color": null,
    "showAddNew": true,
    "showAddNewOnHover": true
  },
  "children": []
}

Checklist

Read-only checklist for arrays of tasks or objectives. Items can be strings or objects. Use labelField, checkedField, and descriptionField to map object fields; metaFields renders extra badges.

Prop Type Required
items any[] yes
labelField string
checkedField string
descriptionField string
metaFields ({ label, field })[]
showProgress boolean
emptyText string
{
  "type": "Checklist",
  "props": {
    "items": [
      {
        "title": "Find the missing caravan",
        "completed": true,
        "description": "Followed the wheel tracks north of town.",
        "owner": "Ranger"
      },
      {
        "title": "Question the bandit captain",
        "completed": false,
        "owner": "Party"
      }
    ],
    "labelField": "title",
    "checkedField": "completed",
    "descriptionField": "description",
    "metaFields": [{"label":"Owner","field":"owner"}],
    "showProgress": true,
    "emptyText": "No objectives"
  },
  "children": []
}

DataTable

Table bound to an array of objects with declared columns — spell lists, inventories with quantity/weight, attack tables. Each column maps a field (dot paths supported, e.g. "item.name"); cells edit inline and save back to that row when the array is a stored field — rows of a computed (expression) array render read-only. Rows cannot be added or removed on the sheet: players edit the rows the file already has. Use type: "number" for numeric columns. For arrays of file references prefer FileReferenceGrid; DataTable is for structured plain-object rows.

Prop Type Required
items any[] yes
columns ({ label, field, type? })[] yes
label string
emptyText string
{
  "type": "DataTable",
  "props": {
    "items": [
      {"name":"Longsword","damage":"1d8","weight":3},
      {"name":"Dagger","damage":"1d4","weight":1}
    ],
    "columns": [
      {"label":"Weapon","field":"name","type":"string"},
      {"label":"Damage","field":"damage","type":"string"},
      {"label":"Weight","field":"weight","type":"number"}
    ],
    "label": "Weapons",
    "emptyText": "No weapons"
  },
  "children": []
}

Rows that pick other files with a value beside each (a recipe's reagents and quantities, an inventory with counts) are a FileReferenceGrid with referenceField and metadataFields: it shows each file's name and edits the values in place. A DataTable over a computed list is read-only.

FormattedDate

Formatted date display. "date" shows "April 29, 2024", "relative" shows "yesterday", "distance" shows "2 days ago". Use color for custom text color.

Prop Type Required
value string | number yes
format "date" | "relative" | "distance"
color string
{
  "type": "FormattedDate",
  "props": {"value":1714400000000,"format":"distance","color":null},
  "children": []
}

FormattedNumber

Formatted number display. "decimal" shows "1,234.56", "currency" shows "$1,234.56", "percent" shows "85%". Use color for custom text color.

Prop Type Required
value number yes
style "decimal" | "currency" | "percent"
currency string
color string
{
  "type": "FormattedNumber",
  "props": {"value":1234.56,"style":"currency","currency":"USD","color":null},
  "children": []
}

Play-time controls

Progress

Progress bar with optional label. color sets the indicator bar color, trackColor sets the background track color. showValue displays "value / max" text. stepper adds hover −/+ buttons that bump the bound value by 1 (clamped to 0..max) — prefer this over pairing a bar with a separate Stepper for the same field. All colors accept any CSS color value. editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.

Prop Type Required
value number yes
max number
label string
color string
trackColor string
showValue boolean
stepper boolean
editPath Record<string, string>
{
  "type": "Progress",
  "props": {
    "value": 75,
    "max": 100,
    "label": "Hit Points",
    "color": "#ef4444",
    "showValue": true,
    "stepper": true
  },
  "children": []
}

Set stepper: true for −/+ buttons rather than adding a separate Stepper for the same field.

Dots

Row of filled/empty dots for small resource pools — spell slots, ki points, uses per rest, condition pips. Bind value to a number field; when the field is editable, clicking a dot sets the value (clicking the topmost filled dot clears it). max is the pool size (defaults to 5, capped at 25 dots) and can also bind to a field. color sets filled dots, emptyColor unfilled dots (any CSS color value). showValue displays "value / max" text. Values bound to expression fields render read-only unless editPath provides a stored write target. editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.

Prop Type Required
value number yes
max number
label string
color string
emptyColor string
size "sm" | "md" | "lg"
showValue boolean
editPath Record<string, string>
{
  "type": "Dots",
  "props": {
    "value": 2,
    "max": 4,
    "label": "Spell Slots",
    "color": "#a78bfa",
    "emptyColor": null,
    "size": "md",
    "showValue": true
  },
  "children": []
}

Stepper

Numeric counter with −/+ buttons for one-tap turn-time edits — hit points, ammo, sorcery points, momentum. Bind value to a number field; each tap saves immediately. min defaults to 0 (set a negative min to allow values below zero), max is uncapped when null and can bind to a field (e.g. {"$state": "/hitPointMax"}), step defaults to 1. showMax renders "23 / 40". The value is also click-to-type editable. editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.

Prop Type Required
value number yes
label string
min number
max number
step number
showMax boolean
color string
size "sm" | "md" | "lg"
editPath Record<string, string>
{
  "type": "Stepper",
  "props": {
    "value": 23,
    "label": "Hit Points",
    "min": 0,
    "max": 40,
    "step": 1,
    "showMax": true,
    "color": "#ef4444",
    "size": "md"
  },
  "children": []
}

Toggle

Single boolean as a one-tap control — inspiration, concentration, death-save boxes, armor-used flags. Bind value to a boolean field; clicking flips and saves it. variant: "switch" (default), "checkbox", or "chip" (a lit/dim pill; onLabel/offLabel override the pill text per state). editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.

Prop Type Required
value boolean yes
label string
variant "switch" | "chip" | "checkbox"
onLabel string
offLabel string
color string
editPath Record<string, string>
{
  "type": "Toggle",
  "props": {
    "value": true,
    "label": "Inspiration",
    "variant": "switch",
    "onLabel": null,
    "offLabel": null,
    "color": null
  },
  "children": []
}

Checkbox

Labeled checkbox for a boolean field. Bind checked to toggle it directly from the rendered view. color sets the checked box color (any CSS color value).

Prop Type Required
checked boolean yes
label string
color string
{
  "type": "Checkbox",
  "props": {"checked":true,"label":"Inspiration","color":null},
  "children": []
}

Switch

Labeled toggle switch for a boolean field — same data shape as Checkbox with a switch look. Bind checked to flip it directly from the rendered view. color sets the on-state color (any CSS color value).

Prop Type Required
checked boolean yes
label string
color string
{
  "type": "Switch",
  "props": {"checked":true,"label":"Concentrating","color":"#34d399"},
  "children": []
}

TrackBoxes

Row of square boxes for health/stress/harm tracks. Two modes: bind value to a number field for a filled-count track (click box N to set, click the topmost filled box to clear), or bind states to a string-array field for multi-state tracks where clicking a box cycles empty → each stateOption → empty (e.g. World of Darkness bashing/lethal/aggravated). stateOptions is [{label, symbol}]; the stored array holds labels. boxes is the track length (default 10, cap 30). groupEvery adds a visual gap every N boxes (e.g. 3 for Blades stress). editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.

Prop Type Required
boxes number
value number
states string[]
stateOptions ({ label, symbol? })[]
groupEvery number
label string
color string
size "sm" | "md" | "lg"
showValue boolean
editPath Record<string, string>
{
  "type": "TrackBoxes",
  "props": {
    "boxes": 7,
    "value": null,
    "states": [],
    "stateOptions": [
      {"label":"Bashing","symbol":"/"},
      {"label":"Lethal","symbol":"X"},
      {"label":"Aggravated","symbol":"*"}
    ],
    "groupEvery": null,
    "label": "Health",
    "color": null,
    "size": "md",
    "showValue": false
  },
  "children": []
}

ConditionToggles

Always-visible roster of toggle chips bound to a string-array field — conditions (poisoned, prone, grappled), exhaustion, status effects. Active chips are lit, inactive ones dim; clicking toggles membership and saves. Unlike BadgeList, the full option set stays visible for at-a-glance combat state. options entries are strings or {label, value?, color?}.

Prop Type Required
value string[] yes
options (string | { label, value?, color? })[]
label string
color string
{
  "type": "ConditionToggles",
  "props": {
    "value": ["Poisoned"],
    "options": ["Poisoned","Prone","Grappled","Frightened","Stunned"],
    "label": "Conditions",
    "color": null
  },
  "children": []
}

Clock

Segmented circular progress clock (Blades in the Dark style) for project clocks, countdowns, and faction progress. Bind value to a number field; clicking a segment fills up to it, clicking the last filled segment clears it. segments is 2-12 (default 4). color fills segments, emptyColor the unfilled ones. editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.

Prop Type Required
value number yes
segments number
label string
color string
emptyColor string
size "sm" | "md" | "lg"
showValue boolean
editPath Record<string, string>
{
  "type": "Clock",
  "props": {
    "value": 3,
    "segments": 6,
    "label": "Escape Route",
    "color": "#f59e0b",
    "emptyColor": null,
    "size": "md",
    "showValue": true
  },
  "children": []
}

TurnTracker

Turn order tracker for encounters/combat. Displays a sorted list of combatants with configurable stats. Each combatant has a "type" field: "character" (stats pulled live from a character page via "page" VFS path and pageFieldMapping) or "monster" (all stats inline — hp, maxHp, ac, etc. — with optional "statBlockPage" for reference only). pageFieldMapping maps combatant field names to character page content fields (e.g. {"hp": "hitPoints"}). Special values: "$title" for page title, "$coverImage" for page image. stats defines which columns to show.

Prop Type Required
combatants any[] yes
round number
currentTurnIndex number
fileTypeSlug string
pageTypeSlug string
pageFieldMapping Record<string, string>
stats ({ label, field, maxField?, display? })[] yes
conditionsField string
notesField string
{
  "type": "TurnTracker",
  "props": {
    "combatants": [
      {
        "type": "character",
        "id": "lonin-1",
        "name": "Lonin Ashwell",
        "page": "/pages/character/lonin-ashwell.json",
        "initiative": 18,
        "conditions": ["blessed"],
        "notes": "Concentrating on Shield of Faith"
      },
      {
        "type": "monster",
        "id": "goblin-1",
        "name": "Goblin 1",
        "statBlockPage": "/pages/monster/goblin.json",
        "hp": 7,
        "maxHp": 7,
        "ac": 15,
        "initiative": 14,
        "conditions": [],
        "notes": ""
      }
    ],
    "round": 1,
    "currentTurnIndex": 0,
    "fileTypeSlug": "character",
    "pageFieldMapping": {
      "name": "$title",
      "image": "$coverImage",
      "hp": "hitPoints",
      "maxHp": "hitPointMax",
      "ac": "armorClass"
    },
    "stats": [
      {"label":"HP","field":"hp","maxField":"maxHp","display":"bar"},
      {"label":"AC","field":"ac","maxField":null,"display":null},
      {
        "label": "Init",
        "field": "initiative",
        "maxField": null,
        "display": null
      }
    ],
    "conditionsField": "conditions",
    "notesField": "notes"
  },
  "children": []
}

Select

Dropdown select. Provide static options array, a fileTypeSlug to populate from files of that type (or fileTypeSlugs when the field targets multiple file types), or both. value is the selected option's value or an object with referenceId plus a readable name. Fields whose schema already declares reference targets need no slug prop.

Prop Type Required
value string | number | { referenceId, name?, label?, title? }
label string
placeholder string
options ({ label, value })[]
fileTypeSlug string
pageTypeSlug string
fileTypeSlugs string[]
{
  "type": "Select",
  "props": {
    "value": "fighter",
    "label": "Class",
    "placeholder": "Choose...",
    "options": [
      {"label":"Fighter","value":"fighter"},
      {"label":"Wizard","value":"wizard"}
    ]
  },
  "children": []
}

VoiceSelect

Voice picker for character dialogue. Bind value to a string field with format "voice". A blank value inherits the GM voice, and the web renderer shows preview controls for each voice. showLabel defaults to true; set it false to hide the label.

Prop Type Required
value string
label string
placeholder string
showLabel boolean
{
  "type": "VoiceSelect",
  "props": {
    "value": "leo",
    "label": "Voice",
    "placeholder": "Use GM voice",
    "showLabel": true
  },
  "children": []
}

References to other files

FileReferenceGrid

Grid of cards showing referenced files with their images and titles. Provide items (array of file reference ids, slugs, names, reference objects, or objects), fileTypeSlug to identify the file type — or fileTypeSlugs listing every target type for multi-type reference fields (the add picker then offers per-type filtering and stores qualified "type/slug" values) — and referenceField for object arrays (e.g. "item" for [{item: {referenceId, name}, quantity: 2}]). Fields whose schema already declares reference targets need no slug prop. Metadata fields like quantity render as badges; they are keys stored on each row of the list (quantity in {item, quantity}) and never read the linked file, so to show the linked files' own fields (a creature's level) use a computed list built with load() in a DataTable. titlePosition moves each card's name: "bottom" (default, below the image), "top" (above the image), "overlay" (over the lower edge of the image), or "hidden". metadataPosition moves the metadata badges: "inline" (default, beside the name), "below" (their own wrapping row under the name — fits longer text values), or "hidden". metadataFields entries accept hidden: true to keep a field editable in the card's edit dialog without displaying it, and label to rename it there; omitting a field from the list removes it from display, editing, and new-row defaults alike. emptyState customizes the full-width empty message and defaults to "None.". showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. addNewVariant defaults to "inline" and accepts "aside" to place one compact add control beside the grid label. imageAspectRatio overrides the card image ratio: "video" (16:9), "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9), "ultratall" (9:32, e.g. tall party-roster portraits).

Prop Type Required
items any[] yes
fileTypeSlug string
pageTypeSlug string
fileTypeSlugs string[]
referenceField string
columns number
size "sm" | "md" | "lg"
imageAspectRatio "video" | "square" | "portrait" | "tall" | "ultrawide" | "ultratall"
label string
showAddNew boolean
showAddNewOnHover boolean
addNewVariant "inline" | "aside"
emptyState string
titlePosition "bottom" | "top" | "overlay" | "hidden"
metadataPosition "inline" | "below" | "hidden"
metadataFields ({ name, type, enum?, hidden?, label? })[]
{
  "type": "FileReferenceGrid",
  "props": {
    "items": [
      {
        "item": {
          "referenceId": "01954f42-592f-7b94-ae2a-dbb99d34b0d8",
          "name": "Staff of Fire"
        },
        "quantity": 2
      },
      {
        "item": {
          "referenceId": "01954f42-592f-7b94-ae2a-dbb99d34b0d9",
          "name": "Potion of Healing"
        },
        "quantity": 3
      }
    ],
    "fileTypeSlug": "items",
    "referenceField": "item",
    "columns": 4,
    "size": "md",
    "label": "Inventory",
    "showAddNew": true,
    "showAddNewOnHover": true,
    "addNewVariant": "inline",
    "emptyState": "None."
  },
  "children": []
}

ReferenceValue

Live value pulled from a referenced file — display another file type's data without copying it. Bind source to a reference field (single or list) and set field to the path to read from each referenced file's content (e.g. "acBonus", "stats.speed"); "$title"/"$name" read the file name. Multiple referenced files join with separator (default ", ") or render as chips with format "badge". Read-only — the value lives on the referenced file. Provide fileTypeSlug when the schema does not already annotate the reference field.

Prop Type Required
source any yes
field string
label string
format "text" | "badge"
separator string
color string
fileTypeSlug string
fileTypeSlugs string[]
pageTypeSlug string
{
  "type": "ReferenceValue",
  "props": {
    "source": {"referenceId":"01954f42-592f-7b94-ae2a-dbb99d34b0d8"},
    "field": "acBonus",
    "label": "Armor Bonus",
    "format": "text",
    "separator": null,
    "color": null,
    "fileTypeSlug": "armor"
  },
  "children": []
}