WiFiManager/docs/PORTAL_CUSTOMIZATION.md

Portal customisation

The stable extension surface is the portal* API and JSON API contract. Templates, undocumented DOM IDs, and SPA routing internals are not consumer extension points.

Supported changes

• portalSetBrand* and portalSetContextIdentityText() for the visible identity.
• portalSetPage*, portalSetAction*, portalSetLayout*, and portalSetBehavior* for built-in capability and layout choices.
• portalAddParameter(), including raw HTML blocks inside parameter-rendering surfaces.
• portalAddInfoSection() and portalAddHomeCard() for structured content.
• portalAppendCss(), portalOverrideCss(), and portalAppendJs() for small presentation enhancements.

WiFiManager wm;

wm.portalSetBrandTitle("Solar Battery Monitor Setup");
wm.portalSetContextIdentityText("Solar Battery Monitor");
wm.portalSetBrandHomeIntro(
    "Connect the monitor to WiFi, then review its battery settings."
);
wm.portalSetPageUpdateVisible(false);
wm.portalSetActionEraseVisible(false);
wm.portalSetLayoutParamsLocation(PortalParamsLocation::SetupPage);

WiFiManagerParameter mqttHost(
    "mqtt_host", "MQTT host", "broker.local", 64,
    "placeholder='broker.local'"
);
wm.portalAddParameter(&mqttHost);

PortalHomeCard summary;
summary.id = "battery";
summary.title = "Battery";
summary.kind = PortalHomeCardKind::KeyValue;
summary.items.push_back({"voltage", "Voltage", "13.2V"});
wm.portalAddHomeCard(summary);

wm.portalAppendJs(
    "document.addEventListener('wm:ready', function(event) {"
    "  console.log('Portal ready', event.detail.boot);"
    "});"
);

Enhancement events

Appended JavaScript may enhance the existing SPA through:

• wm:ready, with event.detail.boot;
• wm:view-changed, with event.detail.route.

It should not replace routing or built-in action flow.

Intentional boundary

The following are fork-level changes, not supported consumer customisation:

• arbitrary home, information, navigation, or shell HTML injection;
• replacing built-in SPA routes or action flows;
• depending on undocumented DOM IDs or private templates;
• adding a new backend-to-frontend workflow without an API contract.

For data and endpoint behaviour, see Portal API.

Back to documentation · project overview.