Schema reference

The widget YAML schema is a recursive tree of nodes and modifiers, decoded by the runner and rendered through SwiftUI at runtime. Each *.yaml or *.yml file in ~/Library/Application Support/ApexDock/widgets/ is one widget.

Top-level entry

id: <string>                      # optional; defaults to filename without .yaml/.yml
command: <string>                 # required, shell command (/bin/sh -c)
interval: <seconds>               # default 60, clamped to >= 1
order: <int>                      # default 0, lower = leftmost
enabled: <bool>                   # default true
location: <string>                # tray | pinned | unpinned | agent | leading | trailing
tooltip: <string>                 # cell hover text
click:                            # cell click action (one of)
  shell: <string>
  url: <string>
  palette: <string>
symbol: <string>                  # SF Symbol — legacy mode (ignored when `view` is set)
icon: <string>                    # path / data: URL — legacy mode
tint: <string>                    # legacy mode
label: <string>                   # legacy mode
output: label | json              # legacy mode (ignored when `view` is set)
history:                          # ring buffers exposed under ${history.<field>}
  <field>: <int>                  # capacity (samples)
view: <Node>                      # rich rendering — see Nodes below
hover: <Node>                     # popover content; rendered with no size cap

When view is set, symbol/icon/tint/label/output are ignored. The script's stdout is parsed as JSON and bound into the tree.

Nodes

A node is a YAML mapping with exactly one of the following kind keys, plus any number of modifier siblings.

Layout

Stack alignment values:

• hstack: top, center (default), bottom, firstTextBaseline, lastTextBaseline
• vstack: leading, center (default), trailing
• zstack: topLeading, top, topTrailing, leading, center (default), trailing, bottomLeading, bottom, bottomTrailing

Display primitives

Control flow

See Control flow for details.

Modifiers

Modifiers apply to the node they're declared on. All optional, all sibling fields of the kind key:

Spec field details

TextSpec

SymbolSpec

ImageSpec

GaugeSpec

SparklineSpec

ProgressSpec

ShapeSpec

ForEachSpec

IfSpec

Bindable values

Numeric and array fields accept either a literal or a binding:

# Literal
value: 42
values: [1, 2, 3, 4, 5]

# Binding
value: "${pct}"
values: "${history.pct}"

Strings always pass through binding interpolation: "${city}, ${temp_f}°F" → "SF, 68°F".

Color values

#RRGGBB, #RRGGBBAA, or a named color: red, orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown, gray, black, white, primary, secondary, accent.

Backgrounds also accept material values: regular, thin, ultraThin.

Click actions

Both top-level click: (cell-wide) and node-level onTap: accept the same shape:

click:
  shell: "open -a 'Activity Monitor'"

# or
click:
  url: "https://example.com"

# or
click:
  palette: "switch to Work"

Inside onTap:, all three fields support ${} interpolation, so url: "${item.html_url}" works for clickable list rows.

Output modes (legacy view-less widgets)

When view: is not set, the widget falls back to the legacy single-icon-with-label model:

These modes are useful when you don't need a rich tree. Most new widgets should use view:.

Limits

• 32 widgets visible per zone (sorted by order, then id; tail dropped with a console warning).
• 5-second wall-clock kill on each command tick.
• Single-process per tick — overlapping ticks are dropped.
• 8-character chip label cap (legacy mode).

Reload semantics

The runner watches ~/Library/Application Support/ApexDock/widgets/ via FSEvents and reloads direct child *.yaml / *.yml files on save (100ms debounce). YAML files outside that folder, hidden files, nested files, and the old parent widgets.yaml file are ignored. Diffing is by id:

• New id → schedule + immediate first tick
• Changed config for same id → restart with new config (preserves history rings if history: matches)
• Removed id → remove from store, kill any in-flight subprocess

A YAML parse error keeps that file's previous valid widget running, leaves other widget files alone, and emits a red warning chip with the filename and parse error in its tooltip.