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,GridandCardtakebgImage(an image URL, or a binding to an image field) andbgImageFit. A Tailwindurl()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 (
valueon play-time controls) save when a player changes them, unless the bound field is computed.editPathsends 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 ({ "
| 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": []
}