Protocol
Node reference
The protocol has ten node types, shared modifiers, and a few fixed lists of values. Each example below is rendered with the same engine used by the widget. The layout page describes how nodes share space.
Modifiers
Every node accepts these modifiers. Write them in the same object as the node's own fields. Use them to give a node a background, a size or padding without a wrapper node.
| Field | Type | Description |
|---|---|---|
padding | number | edges | A number insets all four sides, in points. An object insets only the edges that it names: top, bottom, leading, trailing. The other edges stay at 0. On a phone set to a right-to-left language, leading and trailing swap sides, as in the rest of the layout. |
bg | colour | The fill behind the node. The fill includes the padding and stays inside the corner radius. Text with padding, a bg and a corner looks like a pill. |
border | colour | object | A line inside the node's frame. The line follows corner. A colour draws a line 1 pt wide. {"color": …, "width": …} sets the width. |
corner | number | Corner radius of bg and border, in points. The corner is a continuous curve, as on iOS. |
opacity | number | 0 to 1, applied to the node and everything inside it. |
w | number | "fill" | A width in points, or "fill" for all the width that the parent offers. Without w, the node is the size of its content. See layout. |
h | number | "fill" | A height in points, or "fill". |
minW, maxW | number | Limits on the width. The limits apply to any width, however it is set. A node with "w": "fill" and a maxW gives the rest of its share to its siblings. |
minH, maxH | number | Limits on the height. |
priority | number | When a stack or grid does not have enough room, it truncates the nodes with a lower priority first. Set a higher priority on a node that must not truncate. |
accentable | boolean | Keeps the node legible when the Home Screen is in a tinted mode. |
Text defaults
A container can have a text object. A container is a stack, a grid, a grid
column or a grid row. Every text, timer and symbol node inside the container inherits the
fields of the text object. If containers are nested, the nearest container's
fields are used. A node's own fields override inherited fields.
The text object accepts the fields of a text node, except
text and spans. style and size are
alternatives. A node that sets its own style ignores an inherited
size. A node that sets its own size ignores an inherited
style.
{
"type": "vstack",
"text": { "style": "footnote", "color": "secondary", "monoDigits": true },
"children": [
{ "type": "text", "text": "07:00–15:00" },
{ "type": "text", "text": "Grill", "color": "orange" }
]
} vstack · hstack · zstack
Puts its children in a column, in a row, or one on top of another. Every layout uses these nodes.
| Field | Type | Default | Description |
|---|---|---|---|
children | node[] | [] | Nodes to lay out, in order. |
spacing | number | 8 | Gap between children, in points. The protocol sets the default. The default does not come from SwiftUI. |
align | align | center | Cross-axis alignment. A zstack uses it to position children over one another. |
overflow | clip | drop | clip | What happens to children that do not fit. drop leaves out whole children, lowest priority first and from the end. The stack does not draw part of a child. |
more | node | — | The node shown in place of dropped children. The app replaces every {count} in its text with the number of dropped children. |
text | text defaults | — | Text fields that every text, timer and symbol inside the stack inherits: {"style": "footnote", "color": "secondary"}. |
The root node always fills the widget. A bg on the root node covers the whole widget. Every other node is the size of its content unless you set w or h.
When children do not fit, the stack divides the available room between them. Short children keep their length. Long children are truncated, lowest priority first. The stack draws nothing outside the widget. See layout for the rules.
Put a background shape in a zstack. A shape stretches to the size of the node in front of it. A capsule behind a label is the same size as the label.
{
"v": 1,
"view": {
"type": "hstack",
"spacing": 10,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "vstack",
"spacing": 4,
"align": "leading",
"padding": 10,
"bg": "#232B36",
"corner": 10,
"children": [
{
"type": "text",
"text": "vstack",
"size": 13,
"weight": "semibold",
"color": "white"
},
{"type": "text", "text": "column", "size": 11, "color": "#9AA4B2"},
{
"type": "text",
"text": "align: leading",
"size": 11,
"color": "#9AA4B2"
}
]
},
{
"type": "zstack",
"align": "center",
"padding": 10,
"bg": "#232B36",
"corner": 10,
"children": [
{
"type": "vstack",
"children": [],
"w": 54,
"h": 54,
"corner": 27,
"bg": "indigo"
},
{
"type": "text",
"text": "zstack",
"size": 12,
"weight": "semibold",
"color": "white"
}
]
},
{"type": "spacer"},
{
"type": "vstack",
"spacing": 6,
"align": "trailing",
"children": [
{
"type": "text",
"text": "spacer pushes",
"size": 11,
"color": "#9AA4B2"
},
{
"type": "text",
"text": "this to the edge",
"size": 11,
"color": "#9AA4B2"
}
]
}
]
}
} grid
Cells in rows and columns. Each column is as wide as its widest cell. Use it for tables, rotas and other content that must align.
| Field | Type | Default | Description |
|---|---|---|---|
rows | row[] | [] | Each row is an array of cells, or {"cells": […]} with any of bg, corner, opacity, priority and text. A cell is a node, a string (a text node), or null. |
columns | column[] | — | One object per column: w (a number or "fill"), minW, maxW, align, priority and text. Without columns, every column is as wide as its content and aligns leading. |
spacing | number | 8 | Gap between columns. |
rowSpacing | number | 4 | Gap between rows. |
rowPadding | number | edges | 0 | Inset of every row's cells inside its background. |
align | top | center | bottom | center | The vertical position of cells in their row. |
overflow | clip | drop | clip | drop leaves out whole rows that do not fit, lowest priority first and from the end. |
more | node | — | A row shown in place of dropped rows. The app replaces {count} with the number of dropped rows. |
text | text defaults | — | Text fields that every cell inherits. A column's text overrides the grid's text. A row's text overrides the column's text. |
You do not need to set a width in a grid. The header aligns with the data because every cell in a column has the column's width.
Set "w": "fill" on the column that may truncate. That column takes the room that the other columns leave. If there is not enough room, that column is truncated first. The other columns keep their full width.
String cells make a payload shorter. ["Aisha", "07:00–15:00"] is a row of two text nodes. The text of the grid, the column and the row styles them.
{
"v": 1,
"view": {
"type": "vstack",
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "grid",
"spacing": 10,
"rowSpacing": 3,
"rowPadding": {"top": 3, "bottom": 3, "leading": 6, "trailing": 6},
"text": {"style": "footnote", "color": "white", "lines": 1},
"columns": [
{"w": "fill"},
{"align": "trailing", "text": {"monoDigits": true}},
{"text": {"color": "#9AA4B2"}}
],
"rows": [
{
"cells": ["Name", "Shift", "Role"],
"text": {
"style": "caption2",
"weight": "semibold",
"color": "#6D7786"
}
},
["Aisha Khan", "07:00–15:00", "Grill"],
{
"cells": ["Emma-Louise Fairweather", "11:30–20:00", "Floor"],
"bg": "blue/20",
"corner": 6
},
["Hiro Tanaka", "15:00–21:00", "Porter"]
]
}
]
}
} text
A run of text.
| Field | Type | Default | Description |
|---|---|---|---|
text | string | required | The string to draw. \n starts a new line. |
spans | span[] | — | Use in place of text. The runs wrap as one paragraph. Each run is {"text": …} with any of weight, color, design, italic, monoDigits, tracking, uppercase, strikethrough, underline. |
style | font style | body | Semantic text style. Scales with Dynamic Type. |
size | number | — | Fixed point size. Overrides style. Text with a size does not scale with Dynamic Type. |
weight | font weight | from style | Stroke weight. |
design | font design | default | Typeface variant: default, rounded, serif or monospaced. |
color | colour | primary | Text colour. |
lines | number | — | Maximum number of lines. Text past the maximum truncates with an ellipsis. If lines is not set, there is no maximum. |
align | align | leading | Alignment of wrapped lines within the text block. |
monoDigits | boolean | false | Tabular figures. Every digit has the same width, and the typeface does not change. Timers always use tabular figures. |
minScale | number | 1 | The smallest scale that text can shrink to before it truncates, from 0 to 1. Text does not shrink unless you set minScale. With 0.8, a long line shrinks to 80% before an ellipsis appears. |
italic | boolean | false | Italic. |
tracking | number | 0 | Extra space after every character, in points. |
uppercase | boolean | false | Draw the text in capitals. |
strikethrough, underline | boolean | false | A line through or under the text. |
Use style in preference to size. A semantic style scales when the person has larger text turned on. A fixed size does not scale. Small fixed sizes are the most common accessibility problem in a widget.
Set lines on any text that you did not write. Text that you do not control can be too long. The playground lists everything that truncates. Its Longer text switch shows the effect of a longer name.
Use spans when one line needs two weights or two colours. For example, 18° in bold followed by Partly cloudy in secondary is one paragraph. Two separate text nodes cannot wrap together.
Set monoDigits on columns of times or counts. The digits align and the typeface does not change. Use design: "monospaced" to make all the text look like code. Do not use it to align numbers.
{
"v": 1,
"view": {
"type": "vstack",
"align": "leading",
"spacing": 3,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "text",
"text": "largeTitle bold",
"style": "largeTitle",
"weight": "bold",
"color": "white"
},
{"type": "text", "text": "headline", "style": "headline", "color": "white"},
{
"type": "text",
"text": "body rounded",
"style": "body",
"design": "rounded",
"color": "#9AA4B2"
},
{
"type": "text",
"text": "monospaced 0.84",
"style": "footnote",
"design": "monospaced",
"color": "mint"
},
{
"type": "text",
"text": "A caption long enough to wrap, capped at two lines so it truncates rather than pushing the layout off the widget.",
"style": "caption",
"color": "#6D7786",
"lines": 2
}
]
}
} timer
A date that continues to count on the phone. A timer stays correct without a new fetch.
| Field | Type | Default | Description |
|---|---|---|---|
until | ISO-8601 | required | The date to count toward. If the date is in the past, you can write from. from and until are the same field. |
style | timer style | timer | timer, relative, offset, date or time. |
font | font style | body | Text style. Scales with Dynamic Type. The name is font because style sets the timer style. |
size | number | — | Fixed point size. |
weight | font weight | — | Stroke weight. |
design | font design | default | Typeface variant. |
color | colour | primary | Text colour. |
The phone updates a timer between fetches. A countdown does not need a short refresh. Use a timer for a countdown, and use fetches for data that changed.
The app measures a timer's width when it draws the widget. The width stays the same until the next refresh, but the text continues to change. A timer that counts down is safe, because its text only gets shorter. A timer that counts up gets wider than its measured width: 30 secs becomes 2 min, 28 secs. The longer text draws over the node to its right, or past the edge of the widget. Put a timer that counts up at the end of its row, or on its own line.
The default timer style is different. It takes the full width that it is offered, so its text never draws past its width. It also moves any node beside it to the far edge.
{
"v": 1,
"view": {
"type": "vstack",
"align": "leading",
"spacing": 7,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "text",
"text": "timer",
"size": 10,
"design": "monospaced",
"color": "#6D7786"
},
{
"type": "timer",
"until": "2035-01-01T00:00:00Z",
"size": 20,
"weight": "semibold",
"color": "white"
},
{
"type": "text",
"text": "relative",
"size": 10,
"design": "monospaced",
"color": "#6D7786"
},
{
"type": "timer",
"until": "2035-01-01T00:00:00Z",
"style": "relative",
"size": 14,
"color": "mint"
},
{
"type": "text",
"text": "date",
"size": 10,
"design": "monospaced",
"color": "#6D7786"
},
{
"type": "timer",
"until": "2035-01-01T00:00:00Z",
"style": "date",
"size": 14,
"color": "#9AA4B2"
}
]
}
} symbol
An SF Symbol: one of Apple's thousands of icons. It has the weight and colour of the text around it.
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | The symbol's name, such as cloud.sun.fill. An unknown name draws nothing but keeps its space. |
style | font style | body | The text style that sets the symbol's size and weight. Scales with Dynamic Type. |
size | number | — | Fixed point size, instead of style. |
weight | font weight | — | Stroke weight. |
color | colour | primary | Colour, and the first colour of a palette. |
mode | symbol mode | monochrome | monochrome, hierarchical, palette or multicolor. |
colors | colour[] | — | The second and later colours for palette. |
variable | number | — | 0 to 1, for symbols with a variable value, such as wifi or speaker.wave.3. |
A symbol is a square. Its side is the point size of its font, which is 17 pt for body. On a line of text, the symbol is the same size as the text. Set w or h to draw the symbol bigger. The glyph scales to fit.
Symbols inherit a container's text defaults. A symbol in a row of captions has the caption size and the caption colour without fields of its own.
The preview draws a substitute icon. Apple's licence allows SF Symbols only in apps on Apple platforms, and no browser can draw them. This site shows the nearest icon from Phosphor (MIT). The phone draws the real symbol. The layout is the same in both, because the size of the box does not depend on the glyph. A name with no substitute icon shows a dashed outline on this site.
{
"v": 1,
"view": {
"type": "vstack",
"spacing": 12,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "hstack",
"spacing": 12,
"children": [
{
"type": "symbol",
"name": "cloud.sun.fill",
"size": 26,
"mode": "multicolor",
"color": "orange"
},
{
"type": "symbol",
"name": "battery.75percent",
"size": 26,
"color": "green"
},
{
"type": "symbol",
"name": "wifi",
"size": 26,
"mode": "hierarchical",
"color": "cyan"
},
{"type": "symbol", "name": "heart.fill", "size": 26, "color": "pink"},
{
"type": "symbol",
"name": "star",
"size": 26,
"weight": "ultraLight",
"color": "yellow"
},
{
"type": "symbol",
"name": "star",
"size": 26,
"weight": "black",
"color": "yellow"
}
]
},
{
"type": "hstack",
"spacing": 5,
"text": {"style": "footnote", "color": "#9AA4B2"},
"children": [
{"type": "symbol", "name": "location.fill"},
{"type": "text", "text": "London"},
{"type": "spacer"},
{"type": "symbol", "name": "clock"},
{"type": "text", "text": "Updated just now"}
]
}
]
}
} image
A bitmap fetched over HTTPS. Use it for content that the other nodes cannot draw, such as a chart, a map or a logo.
| Field | Type | Default | Description |
|---|---|---|---|
url | string | required | Absolute https URL. |
fit | fit | fill | fit | fit keeps the whole image visible. fill covers the box and crops the image. |
tint | colour | — | Draws the image as a template in this colour, using its alpha only. |
An image has no size of its own. It stretches to the size that it is given. Set w and h, or set a height inside a column that sets the width. With neither, the image has no size, and the playground reports this.
With tint, a glyph that your server draws stays legible in tinted mode and on the Lock Screen. A photograph without tint does not.
The limit for an image is 2 MB and 2000 px on the longest side. The phone caches images between refreshes.
{
"v": 1,
"view": {
"type": "vstack",
"align": "center",
"spacing": 8,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "text",
"text": "Last 24 hours",
"style": "caption2",
"color": "#6D7786"
},
{
"type": "image",
"url": "https://webhookwidget.com/img/sparkline.png",
"fit": "fill",
"h": 44,
"tint": "cyan"
},
{
"type": "text",
"text": "tint: cyan",
"size": 10,
"design": "monospaced",
"color": "#6D7786"
}
]
}
} gauge · progress
A proportion, drawn as a bar or a ring.
| Field | Type | Default | Description |
|---|---|---|---|
value | number | required | Current value, between min and max. Not needed with from and until. |
min | number | 0 | Lower bound. |
max | number | 1 | Upper bound. Must be greater than min. |
from, until | ISO-8601 | — | Use in place of value. The progress moves between these two dates. The system draws it, so it continues to move between fetches without a new fetch. |
label | string | — | Text drawn inside a ring, or above a bar. |
center | node | — | Any node drawn in the middle of a ring, such as a symbol. Takes the place of label. |
style | bar | ring | bar | Which form to draw. |
tint | colour | accent | Colour of the filled portion. |
track | colour | quaternary grey | Colour of the unfilled portion. The tint at a low opacity, such as green/25, looks like Apple's rings. |
thickness | number | 6 | Line width in points. |
With min and max, you can send real units, such as 24 out of 35 days or 412 of 500 MB. You do not need to convert the value to a fraction.
A bar takes the full width of its parent. A column that contains a bar takes the rest of its row. A ring is the size of the space that it is given. Set w and h to make several rings the same size.
The system's progress view draws a live progress (from and until). It is a thinner bar on a grey track, or a ring on a track of its tint at a low opacity. thickness and track do not apply to it.
{
"v": 1,
"view": {
"type": "vstack",
"spacing": 12,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "gauge",
"value": 412,
"min": 0,
"max": 500,
"label": "412 of 500 MB",
"tint": "blue"
},
{
"type": "hstack",
"spacing": 16,
"align": "center",
"children": [
{
"type": "gauge",
"value": 0.25,
"style": "ring",
"label": "25%",
"tint": "mint",
"w": 52,
"h": 52
},
{
"type": "gauge",
"value": 0.6,
"style": "ring",
"tint": "yellow",
"track": "yellow/25",
"thickness": 9,
"w": 52,
"h": 52,
"center": {
"type": "symbol",
"name": "bolt.fill",
"size": 16,
"color": "yellow"
}
},
{
"type": "gauge",
"value": 0.9,
"style": "ring",
"label": "90%",
"tint": "red",
"w": 52,
"h": 52
},
{
"type": "gauge",
"style": "ring",
"from": "2026-01-01T00:00:00Z",
"until": "2036-01-01T00:00:00Z",
"tint": "green",
"w": 40,
"h": 40
}
]
}
]
}
} rect · circle · capsule
A solid or outlined shape. It stretches to the size that it is given.
| Field | Type | Default | Description |
|---|---|---|---|
fill | colour | — | Fill colour. A shape with neither fill nor stroke is filled in primary. |
stroke | colour | — | Outline colour. The outline is drawn inside the shape, so it stays inside the frame. |
lineWidth | number | 1 | Outline width in points. |
A rect takes its corner radius from corner. A circle is drawn in the largest square that fits. A capsule has fully rounded ends.
A shape has no size of its own. Set w and h for a dot or a cell. Without a size, the shape stretches to the size of its siblings. Beside a block of text, it takes the full height of the row. In a zstack, it takes the size of the label in front of it.
A colour with an opacity gives a translucent fill that still changes with light and dark mode: "fill": "green/20".
{
"v": 1,
"view": {
"type": "vstack",
"align": "leading",
"spacing": 12,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "hstack",
"spacing": 10,
"children": [
{"type": "circle", "fill": "green", "w": 12, "h": 12},
{"type": "circle", "stroke": "orange", "lineWidth": 2, "w": 20, "h": 20},
{"type": "rect", "fill": "indigo", "corner": 6, "w": 40, "h": 24},
{
"type": "capsule",
"fill": "pink/30",
"stroke": "pink",
"lineWidth": 1,
"w": 60,
"h": 24
}
]
},
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 4, "fill": "purple", "corner": 2},
{
"type": "vstack",
"align": "leading",
"spacing": 0,
"children": [
{
"type": "text",
"text": "Design review",
"style": "subheadline",
"weight": "semibold",
"color": "white"
},
{
"type": "text",
"text": "The bar is exactly as tall as this block",
"style": "caption",
"color": "#9AA4B2"
}
]
}
]
}
]
}
} spacer
Takes the room that is left. Use it to move nodes apart without setting sizes.
| Field | Type | Default | Description |
|---|---|---|---|
minLength | number | 0 | The smallest size that the spacer shrinks to when the stack does not have enough room. |
Two spacers in one stack share the spare room equally. This centres the nodes between them.
A spacer is flexible, so w and h do not fix its size. For a fixed gap, use minLength inside a stack that has no spare room, or set spacing on the stack.
The stack measures content first. A spacer does not take room from the nodes that it separates. Text between spacers keeps its full width if the stack has room for it.
A spacer makes its stack fill along the stack's direction. A row with a spacer is as wide as the column that contains it.
{
"v": 1,
"view": {
"type": "vstack",
"spacing": 10,
"padding": 14,
"bg": "#151A21",
"children": [
{
"type": "hstack",
"children": [
{"type": "text", "text": "left", "size": 13, "color": "white"},
{"type": "spacer"},
{"type": "text", "text": "right", "size": 13, "color": "white"}
]
},
{"type": "divider"},
{
"type": "hstack",
"children": [
{"type": "spacer"},
{
"type": "text",
"text": "two spacers centre this",
"size": 13,
"color": "mint"
},
{"type": "spacer"}
]
},
{"type": "spacer"},
{
"type": "text",
"text": "and a spacer above pins this to the bottom",
"size": 11,
"color": "#6D7786"
}
]
}
} divider
A hairline rule across a column, or down a row.
| Field | Type | Default | Description |
|---|---|---|---|
color | colour | separator grey | Colour of the line. |
The line is one physical pixel wide at every scale. It is not thicker on a 3× screen.
In an hstack, the line runs from top to bottom and is as tall as the row. In any other parent, the line runs across the full width that it is given.
{
"v": 1,
"view": {
"type": "vstack",
"align": "leading",
"spacing": 8,
"padding": 14,
"bg": "#151A21",
"children": [
{"type": "text", "text": "Today", "style": "headline", "color": "white"},
{"type": "divider"},
{
"type": "text",
"text": "12 commits",
"style": "footnote",
"color": "#9AA4B2"
},
{"type": "divider"},
{
"type": "text",
"text": "3 reviews",
"style": "footnote",
"color": "#9AA4B2"
}
]
}
} Colours
Where a field accepts a colour, write a semantic name or a hex value. Either can have an
opacity in percent after a slash. Use names where you can. Names adapt to the light and
dark appearances. Names also work in the Home Screen's tinted rendering, and hex values do
not. blue/15 is blue at 15% opacity, and it adapts to both appearances.
"color": "primary" // adapts to light and dark
"color": "accent" // the reader's accent colour
"color": "blue/15" // a semantic colour at 15% — still adapts
"color": "#3DDC84" // six-digit hex
"color": "#3DDC84CC" // eight-digit, with alpha
"color": "#3DDC84/50" // any colour can take an opacity after a slash
"color": "#F0A" // three-digit shorthand
"color": "#F0A8" // four-digit, with alpha The semantic names are not case-sensitive:
primary, secondary and tertiary are the text colours
for the current appearance. accent is the reader's accent colour. The other
names are the system palette. Each system colour has a different RGB value in each
appearance.
A fixed background colour sets the appearance of its content
A fixed colour is any hex value, white or black. If a node has a
bg in a fixed colour, the renderer measures the brightness of that colour. The
renderer then draws everything inside the node in the matching appearance. If the root has
"bg": "#101014", primary is white inside the root on a light Home
Screen and on a dark Home Screen. If a card has "bg": "white",
primary is dark on the card.
Most demos on this site have no Light and Dark control. If a payload sets its own fixed background, the control does nothing, so the site does not show the control. The build checks each demo against the renderer. The control appears only where the two appearances differ.
You can also branch on the scheme request
parameter and send different colours. Read the warning on that page first. iOS renders
one timeline into both appearances. A payload fetched in light mode can be shown in dark
mode, and the phone does not fetch again.
Allowed values
These fields accept one name from a fixed list. An unrecognised name is a decode error. No default is used in its place. See limits and errors.
Font styles
Font styles scale with Dynamic Type. Text with a size does not scale.
Font weights
Overrides the weight that a style sets. For example, headline is semibold by default.
Font designs
rounded is SF Pro Rounded. Large numbers are easy to read in it.
Alignment
All axes use one vocabulary. Each stack applies the values that fit its axis.
Timer styles
timer, relative and offset count on the phone between fetches. date and time draw the date and do not change.
Gauge styles
Symbol modes
palette takes its colours from color then colors. The preview approximates the modes with its substitute icons.
Overflow
drop leaves whole children or rows out, and shows more in their place.
Content fit
Dates
Every date in the protocol is ISO 8601. This applies to until,
from and an entry's at. The protocol accepts
2026-08-11T12:00:00Z and the fractional-second form, with or without a numeric
UTC offset.