Skip to content

Widget catalogue ​

All 30 widget types of protocol v1. Every example uses Ui& ui = face.ui();. The screenshots show the web renderer in light or dark, following the site theme; the apps draw the same widgets natively.

Common props ​

These apply to every widget unless a type says otherwise.

PropBuilderTypeMeaning
idfirst argumentstringRequired, unique, A-Za-z0-9_, 1 to 15 characters
tythe builder methodstringWidget type
lblsecond argumentstringLabel
grp.group(id)stringId of the group card the widget belongs to
page.page(id)stringId of the page; absent means the first page
row.row(id)stringId of a row; widgets in one row sit side by side
size.size(w, h=0)number or [w, h]Relative width in a row (default 1), h fixed height in px
sq.square()boolSquare aspect
dis.disabled()boolDisabled
visui.show(id, bool)boolVisible (default true; changed at runtime via prop)
hint.hint(text)stringHelp text on long-press or hover
icon.icon(name)stringIcon name from the shared set
ro.readOnly()boolRendered but not settable; a set is answered with err 7
color.color("#rrggbb")stringAccent color, only on types that list it

Value handling in short: face.set(id, v) writes a value (bool, int, uint32_t, float, const char*; joystick takes set(id, x, y)). onChange picks the conversion from its argument type: bool, int, uint32_t, float, double, const Str&, const char* or const Value&. Defaults across the catalogue: min 0, max 100, step 1, win 300, rows 5, cap 200, digits 4, zoom 12, mode datetime, center false, fold false, legend true, vals false, style the first value listed.

Outputs ​

label ​

label widgetlabel widget

cpp
ui.label("state", "State", "text");
PropTypeDefaultMeaning
unitstringnoneUnit suffix
fmtstringnoneprintf-style format for numbers, .fmt("%.2f")

Value: string or number, face.set("state", "idle").

gauge ​

gauge widgetgauge widget

cpp
ui.gauge("temp", "Temperature", 0, 120, "°C").style("round").zone(90, 120, "#ff0000");
PropTypeDefaultMeaning
min, maxnumber0, 100Range
unitstringnoneUnit
zones[{from,to,color}]noneColored ranges, .zone(from, to, color) repeatable
stylearc, round, lineararcLook

Value: number, face.set("temp", 42.5f).

progress ​

progress widgetprogress widget

cpp
ui.progress("bal", "Balance", -100, 100).center();
PropTypeDefaultMeaning
min, maxnumber0, 100Range
centerboolfalseBipolar bar growing from the middle
colorstringthemeBar color

Value: number.

display ​

display widgetdisplay widget

cpp
ui.display("disp", "Pressure", 5, "bar");
PropTypeDefaultMeaning
digitsint4Number of 7-segment digits
unitstringnoneUnit

Value: number or string.

led ​

led widgetled widget

cpp
ui.led("ok", "OK", "#00ff00");
ui.led("rgb", "Status").rgb();
PropTypeDefaultMeaning
colorstringthemeOn color
rgbboolfalseThe value is a color instead of on/off

Value: bool, or int 0xRRGGBB with .rgb(): face.set("rgb", (uint32_t)0x00ff00).

chart ​

chart widgetchart widget

cpp
ui.chart("tchart", "Temp history", 600, "°C")
    .series("temp", "Temp", "#ff8800").series("target", "Target", "#0088ff")
    .style("area").legend(true).values(false);
face.push("tchart", "temp", t);
PropTypeDefaultMeaning
series[{id,lbl,color}]noneSeries, .series(id, lbl, color) repeatable
winnumber (s)300Time window
unitstringnoneUnit
styleline, bar, arealineLook
legendbooltrueShow legend
valsboolfalseShow current values

No value; points arrive as pts messages, sent by face.push(chartId, seriesId, v). Clients keep a ring buffer sized by win, at most 5000 points per series.

log ​

log widgetlog widget

cpp
ui.log("term", "Log", 200, 8);
face.log("term", "pump started", "#00aa00");
PropTypeDefaultMeaning
rowsint5 (builder: 8)Visible rows
capint200Lines kept by the client (clients keep at most 2000)

No value; lines arrive as log messages through face.log(id, msg, color). face.log(msg) without id goes to the device console view.

table ​

table widgettable widget

cpp
ui.table("tbl", "Zones").column("Zone", 2).column("°C", 1, "right");
face.setRows("tbl", "[[\"Kitchen\",21.5],[\"Bath\",23]]");
PropTypeDefaultMeaning
cols[{lbl,w,align}]none.column(lbl, w=1, align="left"), at least one required

Value: array of rows (string or number cells), set with face.setRows(id, json).

image ​

image widgetimage widget

cpp
ui.image("img", "Diagram", "https://example.com/diagram.png");
ui.prop("img").src("https://example.com/other.png");
PropTypeDefaultMeaning
srcstringrequiredImage URL, changeable with prop

No value. The client loads the URL itself.

stream ​

stream widgetstream widget

cpp
ui.stream("cam", "Camera", "http://192.168.1.60:81/stream");
PropTypeDefaultMeaning
srcstringrequiredMJPEG stream URL

No value.

clock ​

clock widgetclock widget

cpp
ui.clock("now", "Device time", "HH:mm:ss");
PropTypeDefaultMeaning
fmtstringclient defaultTime format

Value: int unix seconds. The library pushes the device time every minute and the client ticks it locally.

map ​

map widgetmap widget

cpp
ui.map("pos", "Location", 14);
face.setPoints("pos", "[[52.52,13.405,\"Boiler\"]]");
PropTypeDefaultMeaning
zoomint12Initial zoom

Value: array of [lat, lon, lbl], set with face.setPoints(id, json). Tiles load from the internet; the web renderer fetches Leaflet lazily from cdnjs.

textblock ​

textblock widgettextblock widget

cpp
ui.textblock("help", "Set the target and enable the pump.");
PropTypeDefaultMeaning
textstringrequiredParagraph, changeable with ui.prop(id).text(..)

No value.

Inputs ​

button ​

button widgetbutton widget

cpp
ui.button("reset", "Reset error").icon("restart_alt").onClick([] { err = 0; });
ui.button("horn", "Horn").hold().onEvent([](int v) { digitalWrite(HORN, v); });
PropTypeDefaultMeaning
colorstringthemeButton color
holdboolfalseSend press (1) and release (0)

No value; the client sends ev. onClick runs on a tap, onEvent(int) receives 1 on press and 0 on release for hold buttons.

switch ​

switch widgetswitch widget

cpp
ui.sw("pump", "Pump").labels("ON", "OFF").onChange([](bool on) { digitalWrite(PUMP, on); });
PropTypeDefaultMeaning
on, offstringnoneState labels, .labels(on, off)
colorstringthemeAccent

Value: bool. The builder method is sw, not switch.

slider ​

slider widgetslider widget

cpp
ui.slider("target", "Target", 20, 90, 1, "°C").persist().onChange([](float v) { target = v; });
PropTypeDefaultMeaning
min, max, stepnumber0, 100, 1Range and step
unitstringnoneUnit
colorstringthemeAccent

Value: number (float).

number ​

number widgetnumber widget

cpp
ui.number("cycles", "Cycles", 0, 10).spin().bind(cycles);
PropTypeDefaultMeaning
min, max, stepnumber0, 100, 1Range and step
unitstringnoneUnit
spinboolfalseShow plus and minus buttons

Value: number (float; bind(int&) also works). Out-of-range values are answered with err 7.

text ​

text widgettext widget

cpp
ui.text("name", "Name", 32).regex("^[A-Za-z ]*$").persist().onChange([](const Str& s) { });
ui.text("pw", "Password", 64).secret();
PropTypeDefaultMeaning
maxlenint64 (builder)Maximum length
secretboolfalseMask the input
restringnoneRegular expression the value must match

Value: string.

textarea ​

textarea widgettextarea widget

cpp
ui.textarea("notes", "Notes", 512, 4).persist();
PropTypeDefaultMeaning
maxlenint256 (builder)Maximum length
rowsint5 (builder: 4)Visible rows

Value: string.

select ​

select widgetselect widget

cpp
ui.select("mode", "Mode", {"Off", "Auto", "Manual"}).style("seg").onChange([](int i) { mode = i; });
ui.prop("mode").options({"Off", "Eco", "Turbo"});
PropTypeDefaultMeaning
optsstring[]requiredOptions, changeable with prop(id).options({..})
stylelist, seglistDropdown or segmented control

Value: int index.

flags ​

flags widgetflags widget

cpp
ui.flags("days", "Days", {"Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"}).persist().onChange([](uint32_t m) { days = m; });
PropTypeDefaultMeaning
optsstring[]requiredCheckbox labels, at most 32

Value: int bitmask, bit 0 is the first option.

color ​

color widgetcolor widget

cpp
ui.color("col", "Light").persist().onChange([](uint32_t rgb) { face.set("rgb", rgb); });

No type-specific props. Value: int 0xRRGGBB.

datetime ​

datetime widgetdatetime widget

cpp
ui.datetime("start", "Start", "time").persist();
PropTypeDefaultMeaning
modedate, time, datetimedatetimeWhat the picker offers, .mode(..)

Value: int unix seconds. In time mode the value is seconds since midnight in the demo UI.

joystick ​

joystick widgetjoystick widget

cpp
ui.joystick("joy", "Valve").center().square().onMove([](int x, int y) { vx = x; vy = y; });
face.set("joy", 0, 0);
PropTypeDefaultMeaning
centerboolfalseSprings back to the middle on release
expboolfalseExponential response curve

Value: pair [x, y], each -100 to 100.

dpad ​

dpad widgetdpad widget

cpp
ui.dpad("pad", "Move").onEvent([](int k) {   // 'u','d','l','r','c' on press, 0 on release
  if (k) Serial.printf("dpad %c\n", (char)k);
});

No type-specific props, no value; the client sends ev with v.

Structure ​

header widgetheader widget

cpp
ui.header("Fake boiler");

No props beyond the label.

group ​

group widgetgroup widget

cpp
ui.group("sensors", "Sensors").fold();
ui.gauge("temp", "Temperature", 0, 120).group("sensors");
PropTypeDefaultMeaning
foldboolfalseCard can be collapsed by tapping its header; it starts open and the fold state lives in the client

Declare it before the widgets that join it.

page ​

page widgetpage widget

cpp
ui.page("setup", "Setup").icon("settings");

A page becomes a tab or bottom-navigation entry. Widgets declared afterwards belong to it.

row ​

row widgetrow widget

cpp
ui.group("control", "Control");
ui.row("r1").group("control");
ui.sw("pump", "Pump").row("r1").size(2);
ui.slider("target", "Target", 20, 90, 1, "°C").row("r1").size(3);

Widgets with the same row sit side by side; size sets their relative widths.

spacer ​

spacer widgetspacer widget

cpp
ui.row("r1");
ui.button("start", "Start").row("r1");
ui.spacer("sp", 1, 16).row("r1");
ui.button("stop", "Stop").row("r1");

spacer(id, w=1, h=8) adds empty space of the given relative width and pixel height.

Unknown types ​

A renderer shows any widget type it does not know as a placeholder labelled "unsupported widget". ui.add(WType, id, lbl) creates any type without builder defaults.

MIT licensed. Firmware, web renderer and apps.