Webhook Widget
Menu Layout

Protocol

Layout

The protocol defines its own layout rules. The widget and this site follow the same rules. You can see what happens when content does not fit before the widget is on a Home Screen.

A node is the size of its content unless a field sets its size. A stack shares its space between its children. Nothing is drawn outside the widget. The rest of this page describes these three rules in detail.

Sizes

By default, a node is the size of its content. A text is as wide as its words. A stack is as big as its children. Two values change the size, on either axis:

  • "w": 120 makes a node 120 points wide.
  • "w": "fill" makes a node take all the width that its parent offers. A node that contains a filling child also fills. This continues outwards until a node that has a number for its size.

minW, maxW, minH and maxH then limit the result. The root always fills the widget, so a bg on the root covers the whole widget.

Sharing a row

A stack first gives every child the size it asks for. If the children fit, the space that remains goes to the children that can grow. These are spacers, nodes that fill, and content that stretches, such as shapes and bars. If the children do not fit, the stack cuts the longest children first, towards a common length. Short children keep their full length. No child is cut to less than an ellipsis.

Worked example
hstack: [ "Wolverhampton Wanderers" (115 pt), spacer, "12:00" (25 pt) ]
in 120 pt:

  bases:     115 + 0 + 25 = 140  → 20 pt short
  cut:       both towards a common length, never below "…"
             → name 95 pt, time 25 pt (already shorter than 95, so untouched)
  result:    "Wolverhampton Wand…"  then  "12:00"
Which child is cut
json
{
  "v": 1,
  "view": {
    "type": "vstack",
    "align": "leading",
    "spacing": 10,
    "padding": 14,
    "bg": "#151A21",
    "text": {"color": "white"},
    "children": [
      {
        "type": "text",
        "text": "A long name and a time",
        "style": "caption2",
        "color": "#6D7786"
      },
      {
        "type": "hstack",
        "children": [
          {
            "type": "text",
            "text": "Wolverhampton Wanderers",
            "style": "headline",
            "lines": 1
          },
          {"type": "spacer"},
          {
            "type": "text",
            "text": "12:00–20:45",
            "style": "headline",
            "monoDigits": true
          }
        ]
      },
      {
        "type": "text",
        "text": "Two long texts side by side",
        "style": "caption2",
        "color": "#6D7786"
      },
      {
        "type": "hstack",
        "children": [
          {
            "type": "text",
            "text": "Design review with Priya and Sam",
            "style": "subheadline",
            "lines": 1
          },
          {
            "type": "text",
            "text": "Conference room 4B, second floor",
            "style": "subheadline",
            "color": "#9AA4B2",
            "lines": 1
          }
        ]
      },
      {
        "type": "text",
        "text": "The same, with priority: 1 on the room",
        "style": "caption2",
        "color": "#6D7786"
      },
      {
        "type": "hstack",
        "children": [
          {
            "type": "text",
            "text": "Design review with Priya and Sam",
            "style": "subheadline",
            "lines": 1
          },
          {
            "type": "text",
            "text": "Conference room 4B, second floor",
            "style": "subheadline",
            "color": "#9AA4B2",
            "lines": 1,
            "priority": 1
          }
        ]
      }
    ]
  }
}
The time keeps its full width because it is shorter than the name. The two long texts are cut to the same length. When the room has priority 1, only the subject is cut.

priority sets the order in which children are cut. The stack cuts children with a lower priority first, as far as possible, before it cuts any child with a higher priority. The default priority is 0. To protect one node, such as the time, the price or the status, give that node a higher priority. In most rows, one such node is enough. A node with a number for its own w is never cut.

Filling

Children with "w": "fill" share the remaining space equally. Their content does not change the share, so two tiles that fill are always the same width. A bar gauge fills its row without a w. A column that contains a bar gauge takes the rest of its row. This puts a progress line between two airport codes, and the payload contains no width.

Equal tiles, and a bar between two labels
json
{
  "v": 1,
  "view": {
    "type": "vstack",
    "spacing": 10,
    "padding": 14,
    "bg": "#151A21",
    "text": {"color": "white"},
    "children": [
      {
        "type": "hstack",
        "spacing": 8,
        "children": [
          {
            "type": "text",
            "text": "Lamp",
            "style": "footnote",
            "weight": "semibold",
            "w": "fill",
            "padding": 10,
            "bg": "#2A3340",
            "corner": 10
          },
          {
            "type": "text",
            "text": "Living room thermostat",
            "style": "footnote",
            "weight": "semibold",
            "w": "fill",
            "padding": 10,
            "bg": "#2A3340",
            "corner": 10,
            "lines": 1
          }
        ]
      },
      {
        "type": "hstack",
        "spacing": 10,
        "children": [
          {"type": "text", "text": "LHR", "style": "title3", "weight": "bold"},
          {
            "type": "vstack",
            "spacing": 2,
            "children": [
              {
                "type": "symbol",
                "name": "airplane",
                "style": "caption",
                "color": "cyan"
              },
              {"type": "gauge", "value": 0.42, "tint": "cyan", "thickness": 4}
            ]
          },
          {"type": "text", "text": "JFK", "style": "title3", "weight": "bold"}
        ]
      }
    ]
  }
}

Stretching

Shapes, images, gauges and dividers have no size of their own. They stretch to fill the space they are given. Across a stack, they match the size of their siblings. A thin rect beside a block of text is as tall as the text. A capsule behind a label in a zstack is as big as the label. For a pill, you can also put a bg and a corner on the label. This gives the same result in one node.

A bar as tall as its text, and two pills
json
{
  "v": 1,
  "view": {
    "type": "vstack",
    "align": "leading",
    "spacing": 12,
    "padding": 14,
    "bg": "#151A21",
    "text": {"color": "white"},
    "children": [
      {
        "type": "hstack",
        "spacing": 8,
        "children": [
          {"type": "rect", "w": 4, "fill": "purple", "corner": 2},
          {
            "type": "vstack",
            "align": "leading",
            "spacing": 1,
            "children": [
              {
                "type": "text",
                "text": "Design review",
                "style": "subheadline",
                "weight": "semibold"
              },
              {
                "type": "text",
                "text": "15:00 – 16:00 · Room 4B",
                "style": "caption",
                "color": "#9AA4B2"
              }
            ]
          }
        ]
      },
      {
        "type": "hstack",
        "spacing": 8,
        "children": [
          {
            "type": "zstack",
            "children": [
              {"type": "capsule", "fill": "green/25"},
              {
                "type": "text",
                "text": "On time",
                "style": "caption",
                "weight": "semibold",
                "color": "green",
                "padding": {"leading": 8, "trailing": 8, "top": 3, "bottom": 3}
              }
            ]
          },
          {
            "type": "text",
            "text": "Delayed 12 min",
            "style": "caption",
            "weight": "semibold",
            "color": "orange",
            "padding": {"leading": 8, "trailing": 8, "top": 3, "bottom": 3},
            "bg": "orange/20",
            "corner": 9
          }
        ]
      }
    ]
  }
}

When it does not fit

Text does not shrink unless you set minScale. A text that does not fit wraps at spaces, stops at lines, and truncates the last line with an ellipsis. If you set minScale, the text shrinks first. With 0.8, the text shrinks to 80% of its size before the ellipsis appears.

Lists can drop whole rows. With "overflow": "drop", a stack or grid that does not have enough space leaves out whole children. It leaves out the lowest priority first, and starts from the end. It shows more in their place, with {count} filled in. Your server sends every row. The phone decides how many rows fit at the reader's text size.

Six events, as many as fit
json
{
  "v": 1,
  "view": {
    "type": "vstack",
    "align": "leading",
    "spacing": 6,
    "padding": 14,
    "bg": "#151A21",
    "text": {"color": "white"},
    "children": [
      {"type": "text", "text": "Today", "style": "headline"},
      {
        "type": "vstack",
        "align": "leading",
        "spacing": 4,
        "overflow": "drop",
        "more": {
          "type": "text",
          "text": "+{count} more",
          "style": "caption",
          "color": "#9AA4B2"
        },
        "text": {"style": "subheadline"},
        "children": [
          {"type": "text", "text": "09:00  Standup"},
          {"type": "text", "text": "11:30  Design review"},
          {"type": "text", "text": "14:00  1:1 with Alex"},
          {"type": "text", "text": "15:30  Interview"},
          {"type": "text", "text": "16:30  Retro"},
          {"type": "text", "text": "18:00  Climbing"}
        ]
      }
    ]
  }
}
The list keeps whole rows and shows how many it left out. A bigger widget shows more rows.

Content that is still too big starts at the top. Content larger than its space starts at the top-leading corner and runs off the bottom and trailing edges. The end of a list is cut, and the heading is not.

The exact rules

The full specification is in the protocol document, and it covers every case. Both renderers are built from that document. Both are tested against the same set of layouts, frame by frame. If the preview and the phone differ, that is a bug. Tell us at contact.