Use type: "arc" for a read-only circular progress ring or a small spinning loading indicator. It is supported in primitives and widgets by compatible Studio previews, the Simulator and Dock firmware. These controls need no additional permission.
type: "arc"
primitives
widgets
Bind a numeric state value to an arc. The default maximum is 1; use max: 100 for percentages. Values are clamped to the range from zero to the maximum. Missing, nonnumeric and nonfinite values render an empty ring.
1
max: 100
{"id":"completion","type":"arc","x":40,"y":120,"w":160,"h":160,"bind":"percent","max":100,"thickness":12,"color":[83,255,175,255]}
Publish { "percent": 75 } to show three quarters of the ring. A primitive can use a static value instead of a binding; widget values come from their bindings. Arcs do not accept input or emit events.
{ "percent": 75 }
value
Set indeterminate: true. The renderer rotates the indicator continuously without repeated state publications or plugin timers. Use a widget's visible binding to show it only while work is pending.
indeterminate: true
visible
{"id":"loading","type":"arc","x":240,"y":170,"w":32,"h":32,"indeterminate":true,"thickness":3,"duration":1000,"visible":"loading"}
Publish { "loading": true } to show it, then false when the operation finishes. Rotation pauses when hidden and is released when the control closes. A static primitive spinner does not introduce a host dependency; widgets retain the existing host execution requirements.
{ "loading": true }
false
w
h
thickness
color
fill
startAngle
sweepAngle
rounded
true
max
duration
Loading indicators and image animations share a projection-wide budget of eight animations, including inactive pages. All arcs must fit within the existing projection geometry and node budgets.
An image primitive or widget can use animation: { "type": "rotate", "duration": 1000, "repeat": true }. Rotation is around its center, clockwise from 0 to 360 degrees by default. Use to: -360 to rotate counterclockwise. Explicit from and to values must be within −360 to 360 degrees. Existing image animation delays and playback rules apply.
animation: { "type": "rotate", "duration": 1000, "repeat": true }
0
360
to: -360
from
to
The device must advertise arc for rings. Image rotation requires both image.animation.v1 and image.rotate.v1. Older firmware rejects unsupported projections through capability checks; update the Simulator or Dock firmware before installing them.
arc
image.animation.v1
image.rotate.v1
The CLI, standalone MCP, Studio MCP and Create context expose these controls through the shared SDK guidance and visuals metadata. Use the same JSON fields in every authoring route. Existing runtime permissions, consent and installation flows are unchanged.
visuals