Complete Syntax Reference

This page is the FULL syntax reference.

It is verified against the current ToonUI source code:

catalog
parser
validator
exported node types

Use it when you need:

the canonical syntax
one concrete example
the required structure
the valid parent/child relationship

Quick path

Read the node syntax exactly as written.
Copy the verified example.
Check the structure notes before nesting nodes.

Core rules

ToonUI lives inside fenced toon-ui blocks
Containers usually end with :
Actions must be explicit with reply="..." or submit
Use only official nodes
Structural child nodes are valid only inside their correct parent

Root nodes

`text`

Syntax

text "Visible text"

Example

text "Customer created successfully."

`heading`

Syntax

heading <1-6> "Visible text"

Example

heading 2 "Customer details"

`separator`

Syntax

separator
separator horizontal
separator vertical

Example

separator vertical

`card`

Syntax

card "Title":

Example

card "Customer found":
  text "Jefferson Lopez Mendoza"
  badge "Active" success
  button secondary "View history" reply="view-history"

`form`

Syntax

form "Title":

Required structure

one or more field
one submit button

Example

form "Create product":
  field name text "Name" required
  field price number "Price" required
  button primary "Create product" submit

`field`

Syntax

field <name> <fieldType> "Label" [placeholder="..."] [helper="..."] [required] [options="A|B"] [min=<number>] [max=<number>] [step=<number>] [value="..."]

Example

field email email "Email" placeholder="name@company.com" required

Field types

text, email, number, password, date, time, textarea, select, checkbox, radio, switch, combobox, otp, slider, multiselect

Extra rules

select, radio, and multiselect require options
slider uses min, max, and optional step
value is parsed from a quoted attribute like value="7" or value="true"

`button`

Syntax

button <variant> "Label" reply="Value"
button <variant> "Label" submit

Example

button primary "Create product" reply="start-create-product"
button primary "Save" submit

Required rule

must include variant, label, and reply="..." or submit

`confirm`

Syntax

confirm <variant> "Title":

Compatibility note

the parser still accepts confirm "Title": and defaults it to neutral
the canonical syntax should still use an explicit variant

Example

confirm danger "Delete customer?":
  text "This action cannot be undone."
  button secondary "Cancel" reply="cancel"
  button danger "Delete" reply="delete-customer"

`list`

Syntax

list "Title":

Required structure

only item children

Example

list "Products":
  item "Toon Mug":
    text "Ceramic mug"

`item`

Syntax

item "Title":

Example

item "Candy":
  text "Ready to publish"

`badge`

Syntax

badge "Label" <variant>

Example

badge "Active" success

`alert`

Syntax

alert <variant> "Title":

Example

alert warning "Inventory mismatch":
  text "The counted stock does not match the expected total."

`table`

Syntax

table "Title":

Required structure

columns:
one or more row:

Example

table "Sales":
  columns: "Date", "Sale number", "Total", "Status"
  row: "May 14", "S-001", "$25.00", "Paid"
  row: "May 15", "S-002", "$48.00", "Pending"

`empty`

Syntax

empty "Title":

Example

empty "No customers found":
  text "Try another search term."
  button secondary "Search again" reply="search-again"

`tabs`

Syntax

tabs "Title":

Required structure

one or more tab

Example

tabs "Customer profile":
  tab "Summary":
    text "Customer is active."
  tab "History":
    text "Last order was yesterday."

`accordion`

Syntax

accordion "Title":

Required structure

one or more section

Example

accordion "Advanced settings":
  section "Inventory":
    text "Sync runs every 15 minutes."
  section "Billing":
    text "Invoices close on the last day of the month."

`dialog`

Syntax

dialog "Title":

Example

dialog "Customer details":
  text "This is modal content."

`sheet`

Syntax

sheet "Title" side="left|right|top|bottom":

Example

sheet "Filters" side="right":
  text "Choose the filters to apply."

Compatibility note

if side is omitted, the parser defaults to right

Syntax

popover "Title":

Example

popover "More details":
  text "Extra context for this result."

Syntax

tooltip "Visible text"

Example

tooltip "More information"

`progress`

Syntax

progress "Label" value=<number> max=<number>

Example

progress "Uploading files" value=2 max=5

`loading`

Syntax

loading "Visible text"

Example

loading "Searching products..."

`toast`

Syntax

toast <variant> "Visible text"

Example

toast success "Customer created successfully."

Syntax

breadcrumb:

Required structure

one or more crumb

Example

breadcrumb:
  crumb "Customers" reply="go:customers"
  crumb "Jefferson Lopez"

`pagination`

Syntax

pagination page=<number> totalPages=<number>

Example

pagination page=2 totalPages=7

Syntax

menu "Title":

Required structure

one or more action

Example

menu "Quick actions":
  action "Create sale" reply="start-sale"
  action "View inventory" reply="show-inventory" variant="secondary"

`command`

Syntax

command "Title":

Required structure

one or more action

Example

command "Jump to":
  action "Open reports" reply="open-reports"
  action "Create product" reply="start-create-product"

`chart`

Syntax

chart <type> "Title":

Required structure

one or more series
each series contains one or more point

Optional attributes

x="..."
y="..."

Example

chart bar "Weekly sales" x="Day" y="Revenue":
  series "Store A":
    point "Mon" 1200
    point "Tue" 980

Minimal example

chart line "Weekly sales":
  series "Store A":
    point "Mon" 24
    point "Tue" 31

Structural child nodes

These nodes are part of the language, but they do NOT live on their own.

`tab`

Only valid inside

tabs

Syntax

tab "Label":

`section`

Only valid inside

accordion

Syntax

section "Title":

`crumb`

Only valid inside

breadcrumb

Syntax

crumb "Label" [reply="Value"]

`action`

Only valid inside

menu
command

Syntax

action "Label" reply="Value"
action "Label" submit
action "Label" reply="Value" variant="secondary"

`series`

Only valid inside

chart

Syntax

series "Label":

`point`

Only valid inside

series

Syntax

point "Label" <number>

Common mistakes

button primary "Create product" "start-create-product"

Wrong because button needs reply="..." or submit.

action "Create sale" "start-sale"

Wrong because action needs reply="..." or submit.

form "Customer":
  field name text "Name"

Wrong because form needs a submit button.

What NOT to do

1. Do not invent nodes

header "Customer"
modal "Delete product"
grid:
  text "Name"

Wrong because those are not official ToonUI nodes.

2. Do not omit `reply=` or `submit`

button primary "Create product" "start-create-product"
action "Open reports" "open-reports"

Wrong because actions must be explicit.

3. Do not place structural child nodes at the top level

crumb "Customers"
tab "Summary":
  text "Active"
series "Store A":
  point "Mon" 1200

Wrong because:

crumb only works inside breadcrumb
tab only works inside tabs
series only works inside chart

4. Do not use unquoted field default values

field active switch "Active" value=true
field score slider "Score" min=0 max=10 step=1 value=7

Wrong because the parser reads field defaults from quoted value="...".

5. Do not emit incomplete strict nodes

alert "Low stock"
progress 65
pagination 2/8

Wrong because:

alert needs variant + title + : + children
progress needs label + value= + max=
pagination needs page= + totalPages=

6. Do not leave table parsing ambiguous

row: May 09, $ 8,155.35, Completed

Risky because commas inside values can be misread. Quote every cell.

On this page