Skip to content

Ui builder ​

Generated

This page is generated by docs/site/scripts/gen-api.mjs from firmware/src/ui/Ui.h; descriptions and examples live in docs/site/scripts/api-notes.json.

face.ui() returns the default Ui; face.addUi("setup") creates another one that a transport can serve instead. Builder methods return a WidgetRef for chaining; widgets declared after page() belong to that page. The tables below are the overview from the firmware README; the sections that follow list every method.

Every method returns a WidgetRef for chaining. Widgets declared after page() belong to that page.

MethodWidgetValue
page(id, lbl)page (tab)–
header(lbl)header–
group(id, lbl)group card; widgets join it via .group(id)–
row(id)row; widgets join it via .row(id).size(w)–
spacer(id, w=1, h=8)spacer–
label(id, lbl, unit=0)label (output)number or string
button(id, lbl)button; .hold() for press/releaseonClick / onEvent(int)
sw(id, lbl)switch; .labels(on, off)bool
slider(id, lbl, min, max, step=1, unit=0)sliderfloat
number(id, lbl, min, max, step=1, unit=0)number input; .spin()float
text(id, lbl, maxlen=64)text input; .secret(), .regex(re)string
textarea(id, lbl, maxlen=256, rows=4)multi-line textstring
select(id, lbl, {opts})dropdown; .style("seg")int index
flags(id, lbl, {opts})checkbox set (max 32)int bitmask
color(id, lbl)colour pickerint 0xRRGGBB
datetime(id, lbl, mode="datetime")date/time picker; .mode("date"|"time"|"datetime")int unix seconds
joystick(id, lbl)joystick; .center(), .exp()pair, onMove(x, y) each -100..100
dpad(id, lbl)direction padonEvent(int): 'u' 'd' 'l' 'r' 'c' on press, 0 on release
gauge(id, lbl, min, max, unit=0)gauge (output); .style("arc"|"round"|"linear"), .zone(from, to, color)float
progress(id, lbl, min=0, max=100)bar (output); .center() for bipolarfloat
display(id, lbl, digits=4, unit=0)7-segment readout (output)number or string
led(id, lbl, color=0)LED (output); .rgb() makes the value a colourbool, or int 0xRRGGBB with .rgb()
chart(id, lbl, win=300, unit=0)chart; .series(id, lbl, color), .style(), .legend(), .values()face.push(chart, series, v)
log(id, lbl, cap=200, rows=8)log viewface.log(id, msg, color)
table(id, lbl)table (output); .column(lbl, w=1, align="left"), at least onesetRows(id, json)
image(id, lbl, src)image; prop(id).src(url) to change–
stream(id, lbl, src)MJPEG stream–
clock(id, lbl, fmt=0)clock (output); the library pushes the device time every minuteint unix seconds
map(id, lbl, zoom=12)map (output)setPoints(id, json)
textblock(id, text)static paragraph–
add(WType, id, lbl=0)any type, no defaultsper type

Common chain modifiers: .group(id), .page(id), .row(id), .size(w, h=0), .square(), .disabled(), .readOnly(), .hint(text), .icon(name), .color(hex), .unit(u), .range(min, max), .step(s), .value(v), .persist() (NVS, restored before setup() returns), .bind(var) (two-way with a bool/int/float/String), .onChange(lambda) (argument type picks the conversion: bool, int, uint32_t, float, const String&, const Value&).

Runtime callEffect
face.set(id, v)update a value (bool, int, uint32_t, float, const char*); joystick: set(id, x, y)
face.setRows(id, "[[\"Kitchen\",21.5],[\"Bath\",23]]")table rows as a raw JSON array of rows
face.setPoints(id, "[[52.52,13.4,\"Home\"]]")map points [lat, lon, lbl]
face.push(chart, series, v)chart point
face.log(msg) / face.log(id, msg, color)log line, optionally to one log widget
face.toast(lvl, msg)info, warn, err toast on all clients
face.ui().prop(id).label(..).color(..).src(..).min(..).disabled(..).visible(..).options({..})runtime prop change without rebuild
face.ui().show(id, bool)hide/show
face.ui().confirm(id, msg, cb) / prompt(id, msg, cb, def)dialogs on all clients, first answer wins
face.ui().rebuild()resend the UI after structural changes
face.time() / face.setTime(unix)unix time from NTP, the client clock or an RTC

Builder ​

Each call appends one widget; ids must match ^[A-Za-z0-9_]{1,15}$ and be unique within the UI. A group, page or row must be declared before the widgets that reference it.

page ​

cpp
WidgetRef page(const char* id, const char* lbl)

Starts a page (tab / bottom-nav entry); widgets declared afterwards belong to it until the next page().

cpp
ui.page("main", "Boiler").icon("home");
ui.page("setup", "Setup").icon("settings");
cpp
WidgetRef header(const char* lbl)

Section heading (no value).

cpp
ui.header("Boiler");

group ​

cpp
WidgetRef group(const char* id, const char* lbl)

Group card; widgets join it with .group(id). .fold() makes it collapsible.

cpp
ui.group("sensors", "Sensors").fold();
ui.gauge("temp", "Temp", 0, 120).group("sensors");

row ​

cpp
WidgetRef row(const char* id)

Row; widgets join it with .row(id).size(w) and sit side by side with relative widths.

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

spacer ​

cpp
WidgetRef spacer(const char* id, float w = 1, int h = 8)

Empty space with relative width w and height h px.

ArgumentTypeDefaultMeaning
idconst char*–
wfloat1
hint8
cpp
ui.spacer("sp", 1, 16);

label ​

cpp
WidgetRef label(const char* id, const char* lbl, const char* unit = nullptr)

Read-only text or number; .fmt("%.1f") formats numbers.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
unitconst char*nullptr
cpp
ui.label("rssi", "Signal", "dBm").fmt("%d");
face.set("rssi", WiFi.RSSI());

button ​

cpp
WidgetRef button(const char* id, const char* lbl)

Button; onClick for a press, .hold() + onEvent for press (1) and release (0).

cpp
ui.button("reset", "Reset error").hint("Clears the error latch").onClick([] { err = 0; });
ui.button("horn", "Horn").hold().onEvent([](int v) { digitalWrite(HORN, v); });

sw ​

cpp
WidgetRef sw(const char* id, const char* lbl)

Switch (bool); .labels(on, off) sets state labels, .icon() without a label gives an icon-only toggle.

cpp
ui.sw("pump", "Pump").labels("ON", "OFF").onChange([](bool v) { digitalWrite(PUMP, v); });

slider ​

cpp
WidgetRef slider(const char* id, const char* lbl, float min, float max, float step = 1, const char* unit = nullptr)

Slider (float) with range, step and unit.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
minfloat–
maxfloat–
stepfloat1
unitconst char*nullptr
cpp
ui.slider("target", "Target", 20, 90, 1, "°C").persist().onChange([](float v) { target = v; });

number ​

cpp
WidgetRef number(const char* id, const char* lbl, float min, float max, float step = 1, const char* unit = nullptr)

Numeric input; .spin() adds +/- buttons.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
minfloat–
maxfloat–
stepfloat1
unitconst char*nullptr
cpp
ui.number("n", "Cycles", 0, 10).spin().onChange([](int v) { cycles = v; });

text ​

cpp
WidgetRef text(const char* id, const char* lbl, int maxlen = 64)

Single-line text input; .secret() masks it, .regex() validates client-side.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
maxlenint64
cpp
ui.text("name", "Name", 32).regex("^[A-Za-z ]*$").onChange([](const String& s) { name = s; });

select ​

cpp
WidgetRef select(const char* id, const char* lbl, const std::vector<const char*>& opts)

Dropdown (value = option index); .style("seg") renders segmented buttons.

cpp
ui.select("mode", "Mode", {"Off", "Auto", "Manual"}).style("seg").onChange([](int i) { mode = i; });

gauge ​

cpp
WidgetRef gauge(const char* id, const char* lbl, float min, float max, const char* unit = nullptr)

Gauge (output); .style("arc"|"round"|"linear"), .zone(from, to, color) colored ranges.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
minfloat–
maxfloat–
unitconst char*nullptr
cpp
ui.gauge("temp", "Temperature", 0, 120, "°C").style("round").zone(90, 120, "#ff0000");

progress ​

cpp
WidgetRef progress(const char* id, const char* lbl, float min = 0, float max = 100)

Bar (output); .center() draws a bipolar bar from the middle.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
minfloat0
maxfloat100
cpp
ui.progress("level", "Tank");
ui.progress("bal", "Balance", -100, 100).center();

led ​

cpp
WidgetRef led(const char* id, const char* lbl, const char* color = nullptr)

Indicator (bool); .rgb() makes the value a 0xRRGGBB color.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
colorconst char*nullptr
cpp
ui.led("ok", "OK", "#00ff00");
ui.led("rgb", "Status").rgb();
face.set("rgb", (uint32_t)0x0000ff);

chart ​

cpp
WidgetRef chart(const char* id, const char* lbl, int winSeconds = 300, const char* unit = nullptr)

Live chart with a client-side ring buffer of winSeconds; add series with .series(id, lbl, color), feed with face.push().

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
winSecondsint300
unitconst char*nullptr
cpp
ui.chart("tchart", "Temp history", 600, "°C").series("temp", "Temp", "#ff8800").series("target", "Target").values(true);
face.push("tchart", "temp", t);

textblock ​

cpp
WidgetRef textblock(const char* id, const char* text)

Static multi-line paragraph (instructions).

cpp
ui.textblock("help", "Set the target and enable the pump.\nThe horn button is momentary.");

log ​

cpp
WidgetRef log(const char* id, const char* lbl, int cap = 200, int rows = 8)

Log view with a client ring buffer of cap lines and rows visible lines; feed with face.log(id, msg, color). ESPFACE_LOG_HISTORY lines are replayed on connect.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
capint200
rowsint8
cpp
ui.log("term", "Log", 200, 8);
face.log("term", "pump on");

textarea ​

cpp
WidgetRef textarea(const char* id, const char* lbl, int maxlen = 256, int rows = 4)

Multi-line text input.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
maxlenint256
rowsint4
cpp
ui.textarea("notes", "Notes", 512, 4).persist();

flags ​

cpp
WidgetRef flags(const char* id, const char* lbl, const std::vector<const char*>& opts)

Checkbox set; the value is a bitmask (bit i = option i, max 32).

cpp
ui.flags("days", "Days", {"Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"}).onChange([](uint32_t m) { days = m; });

color ​

cpp
WidgetRef color(const char* id, const char* lbl)

Color picker; the value is 0xRRGGBB.

cpp
ui.color("col", "Light").onChange([](uint32_t rgb) { strip.fill(rgb); });

datetime ​

cpp
WidgetRef datetime(const char* id, const char* lbl, const char* mode = "datetime")

Date/time picker (unix seconds); mode is date, time or datetime.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
modeconst char*"datetime"
cpp
ui.datetime("start", "Start", "time").onChange([](int t) { startAt = t; });

joystick ​

cpp
WidgetRef joystick(const char* id, const char* lbl)

Joystick; .center() auto-returns, .exp() exponential response; onMove(x, y) each -100..100.

cpp
ui.joystick("joy", "Valve").center().square().onMove([](int x, int y) { drive(x, y); });

dpad ​

cpp
WidgetRef dpad(const char* id, const char* lbl)

Direction pad; onEvent gets 'u', 'd', 'l', 'r', 'c' on press and 0 on release.

cpp
ui.dpad("pad", "Move").onEvent([](int k) { if (k == 'u') forward(); if (k == 0) stop(); });

display ​

cpp
WidgetRef display(const char* id, const char* lbl, int digits = 4, const char* unit = nullptr)

7-segment style readout (output) with digits and unit.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
digitsint4
unitconst char*nullptr
cpp
ui.display("disp", "Pressure", 5, "bar");
face.set("disp", 1.85f);

table ​

cpp
WidgetRef table(const char* id, const char* lbl)

Table (output); add at least one .column(lbl, w, align), fill with face.setRows().

cpp
ui.table("tbl", "Zones").column("Zone", 2).column("°C", 1, "right");
face.setRows("tbl", "[[\"Kitchen\",21.5],[\"Bath\",23]]");

image ​

cpp
WidgetRef image(const char* id, const char* lbl, const char* src)

Image from a URL the client can reach; change it with ui.prop(id).src(url).

cpp
ui.image("img", "Diagram", "http://192.168.1.60/diagram.png");

stream ​

cpp
WidgetRef stream(const char* id, const char* lbl, const char* src)

MJPEG stream from a URL.

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

clock ​

cpp
WidgetRef clock(const char* id, const char* lbl, const char* fmt = nullptr)

Clock (output); the library pushes the device time every minute and the client ticks locally. fmt tokens: YYYY MM DD HH mm ss.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
fmtconst char*nullptr
cpp
ui.clock("now", "Device time", "HH:mm:ss");

map ​

cpp
WidgetRef map(const char* id, const char* lbl, int zoom = 12)

Map (output, online tiles in the clients); fill with face.setPoints().

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*–
zoomint12
cpp
ui.map("pos", "Location", 14);
face.setPoints("pos", "[[52.52,13.405,\"Boiler\"]]");

add ​

cpp
WidgetRef add(WType ty, const char* id, const char* lbl = nullptr)

Any widget type without the convenience defaults (e.g. for props set entirely by chain calls).

ArgumentTypeDefaultMeaning
tyWType–
idconst char*–
lblconst char*nullptr
cpp
ui.add(WType::Gauge, "p", "Pressure").range(0, 10).unit("bar");

Runtime ​

set ​

cpp
bool set(const char* id, const Value& v)
bool set(const char* id, bool v)
bool set(const char* id, float v)
bool set(const char* id, int v)
bool set(const char* id, uint32_t v)
bool set(const char* id, const char* v)
bool set(const char* id, int x, int y)

Updates a value from the sketch and pushes it (same as face.set()); returns false for unknown ids or invalid values.

cpp
face.ui().set("temp", 21.5f);

setRows ​

cpp
bool setRows(const char* id, const char* rowsJson)

Table rows as a raw JSON array.

cpp
face.ui().setRows("tbl", "[[\"Kitchen\",21.5]]");

setPoints ​

cpp
bool setPoints(const char* id, const char* pointsJson)

Map points as a raw JSON array.

cpp
face.ui().setPoints("pos", "[[52.52,13.4,\"Home\"]]");

tickClocks ​

cpp
void tickClocks(uint32_t unix)

Pushes unix to every clock widget; the core calls it every minute, sketches rarely need it.

cpp
face.ui().tickClocks(face.time());

get ​

cpp
const Value* get(const char* id) const

Current value of a widget (nullptr when unknown).

cpp
const Value* v = face.ui().get("target");
if (v) target = v->asFloat();

prop ​

cpp
PropRef prop(const char* id)

Starts a runtime prop update (see PropRef); sent when the statement ends.

cpp
face.ui().prop("temp").color("#f00").label("Temp (HOT)");

show ​

cpp
void show(const char* id, bool visible)

Hides or shows a widget (vis prop).

cpp
face.ui().show("reset", err != 0);

rebuild ​

cpp
void rebuild()

Bumps rev and resends the whole UI to all clients after structural changes (new widgets added at runtime).

cpp
face.ui().label("late", "Added later");
face.ui().rebuild();

Dialogs and streams ​

confirm ​

cpp
void confirm(const char* id, const char* msg, DialogFn cb, const char* title = nullptr, uint16_t timeoutS = 60)

Opens a confirm dialog on every client; the first answer wins, others are dismissed; without an answer the callback gets ok = false after timeoutS.

ArgumentTypeDefaultMeaning
idconst char*–
msgconst char*–
cbDialogFn–
titleconst char*nullptr
timeoutSuint16_t60
cpp
face.ui().confirm("d1", "Shut down the pump?", [](bool ok, const Str&) { if (ok) digitalWrite(PUMP, 0); });

prompt ​

cpp
void prompt(const char* id, const char* msg, DialogFn cb, const char* def = nullptr, const char* title = nullptr, uint16_t timeoutS = 60)

Opens a text prompt on every client; the callback gets the typed text.

ArgumentTypeDefaultMeaning
idconst char*–
msgconst char*–
cbDialogFn–
defconst char*nullptr
titleconst char*nullptr
timeoutSuint16_t60
cpp
face.ui().prompt("d2", "New device name", [](bool ok, const Str& text) { if (ok) rename(text); }, "Boiler");

push ​

cpp
void push(const char* chartId, const char* seriesId, float v, uint64_t tsMs = 0)

Appends a chart point; tsMs 0 = now (unix ms when known, else uptime ms).

ArgumentTypeDefaultMeaning
chartIdconst char*–
seriesIdconst char*–
vfloat–
tsMsuint64_t0
cpp
face.ui().push("tchart", "temp", t);

logLine ​

cpp
void logLine(const char* logId, const char* msg, const char* color = nullptr)

Log line to a log widget (logId), or to the clients' console view when logId is nullptr.

ArgumentTypeDefaultMeaning
logIdconst char*–
msgconst char*–
colorconst char*nullptr
cpp
face.ui().logLine("term", "overheat", "#f00");

Per-UI PIN ​

pin ​

cpp
Ui& pin(const char* p)

Overrides the device PIN for this UI: "" makes it open, any string sets its own PIN; without a call the global face.setPin() applies.

cpp
face.addUi("setup").pin("");

hasPinOverride ​

cpp
bool hasPinOverride() const

True after pin() was called.

cpp
face.ui().hasPinOverride();

pinOverride ​

cpp
const char* pinOverride() const

The overriding PIN (empty = open).

cpp
face.ui().pinOverride();

Other ​

Ui ​

cpp
Ui(const char* name = "main")
Ui(const Ui& )

Constructed by EspFace; sketches use face.ui() / face.addUi().

ArgumentTypeDefaultMeaning
nameconst char*"main"
cpp
auto& ui = face.ui();

name ​

cpp
const char* name() const

The UI's name (main for the default one).

cpp
face.ui().name();

MIT licensed. Firmware, web renderer and apps.