Portal UI and configuration

WiFiManagerPortalConfig is the supported presentation API for the built-in provisioning portal. It changes product identity and semantic visual tokens; the portal-policy methods below control the visibility and behavior of existing built-in features. WiFiManager continues to own portal routes, forms, navigation, captive behavior, reset, and OTA views.

Apply presentation before autoConnect(), startConfigPortal(), or startWebPortal(). Configure portal policy during boot as well so each portal session begins consistently. Portal text and SVG assets are non-owning, so their RAM or PROGMEM data must have static firmware lifetime. WiFiManager locks presentation while a portal is active so asynchronous responses cannot observe partial configuration; setPortalConfig() returns false if it cannot accept the configuration.

Standalone branded portal

#include <Arduino.h>
#include <WiFiManager.h>

WiFiManager wifi;

namespace {
const char kTitle[] PROGMEM = "Set up Temperature Monitor";
const char kIdentity[] PROGMEM = "Example Devices";
const char kTagline[] PROGMEM = "Reliable setup for connected devices.";
const char kLogoAlt[] PROGMEM = "Example Devices";
const char kLogo[] PROGMEM =
    R"svg(<svg viewBox="0 0 64 64"><circle cx="32" cy="32" r="28"/></svg>)svg";
const char kPage[] PROGMEM = "#f4f7f3";
const char kSurface[] PROGMEM = "#ffffff";
const char kAccent[] PROGMEM = "#347a45";
const char kAccentText[] PROGMEM = "#ffffff";

WiFiManagerPortalConfig kPortalUI;
}

void setup() {
    // Set only the identity values this product needs.
    kPortalUI.title = WiFiManagerPortalText::progmem(kTitle);
    kPortalUI.identityText = WiFiManagerPortalText::progmem(kIdentity);
    kPortalUI.tagline = WiFiManagerPortalText::progmem(kTagline);
    kPortalUI.logo = WiFiManagerPortalAsset::svgFromProgmem(kLogo);
    kPortalUI.logoAltText = WiFiManagerPortalText::progmem(kLogoAlt);

    // Unset theme values retain the built-in style.
    kPortalUI.theme.pageBackground = WiFiManagerPortalText::progmem(kPage);
    kPortalUI.theme.surface = WiFiManagerPortalText::progmem(kSurface);
    kPortalUI.theme.accent = WiFiManagerPortalText::progmem(kAccent);
    kPortalUI.theme.accentText = WiFiManagerPortalText::progmem(kAccentText);
    kPortalUI.theme.cornerRadiusPx = 10;

    if (!wifi.setPortalConfig(kPortalUI)) {
        Serial.println("Portal UI configuration was rejected");
    }
    wifi.autoConnect("Temperature Monitor");
}

void loop() { wifi.process(); }

The complete buildable example is Branded Portal. The compile fixture exercises this API on ESP8266 and ESP32.

Presentation reference

Leave a text or colour value empty, or a radius at 0, to retain the built-in stylesheet value.

Field	Used by
title	Document title and concise setup-page heading
identityText	Company or product name in the header above navigation
tagline	Short product context in the header above navigation
logo.svg, logoAltText	Optional trusted inline SVG and its accessible label
pageBackground, surface, text, mutedText, border	Portal surfaces and text
accent, accentHover, accentText	Primary links and actions
success, danger, dangerHover	Status and destructive actions
cornerRadiusPx, smallCornerRadiusPx	Card and compact-control corners, limited to 64 px

Theme values accept only simple semantic CSS value syntax and are emitted once into a small portal theme block. This is deliberately not a raw CSS or JavaScript injection API. An SVG is a trusted compiled firmware asset, never form, MQTT, or network input.

Portal policy

Use the portal-prefixed methods to constrain a product's use of built-in pages and actions. Configure them during boot, before the portal starts, so a session begins with the intended policy.

// An installer portal that does not expose destructive reset or OTA actions.
wifi.portalSetPageUpdateVisible(false);
wifi.portalSetActionEraseVisible(false);
wifi.portalSetActionRestartVisible(false);

// Keep application settings on their own Setup page.
wifi.portalSetLayoutParamsLocation(PortalParamsLocation::SetupPage);

// Do not show saved passwords or static-IP fields unless the product needs them.
wifi.portalSetFieldPasswordPlaceholderMode(PortalPasswordPlaceholderMode::Hidden);
wifi.portalSetFieldStaticIpVisibility(PortalFieldVisibility::Hidden);
wifi.portalSetFieldStaticDnsVisibility(PortalFieldVisibility::Hidden);

Group	Methods	Use
Pages	portalSetPageInfoVisible(), portalSetPageUpdateVisible(), portalSetPageSetupVisible()	Show only product-appropriate built-in pages.
Actions	portalSetActionEraseVisible(), portalSetActionRestartVisible(), portalSetActionExitVisible(), portalSetActionCloseCaptiveVisible(), portalSetActionBackVisible()	Control existing action affordances; hiding an action is not a security boundary.
Layout	portalSetLayoutParamsLocation()	Put registered parameters on the Wi-Fi page or separate Setup page.
Connection/portal behavior	portalSetBehaviorCaptivePortalEnabled(), portalSetBehaviorConnectOnSave(), portalSetBehaviorExitAllowed(), portalSetBehaviorConnectTimeoutSeconds(), portalSetBehaviorPortalTimeoutSeconds(), portalSetBehaviorAutoReconnect(), portalSetBehaviorApClientCheck(), portalSetBehaviorWebClientCheck()	Set portal behavior through the structured configuration vocabulary.
Field policy	portalSetFieldPasswordPlaceholderMode(), portalSetFieldStaticIpVisibility(), portalSetFieldStaticDnsVisibility()	Limit password disclosure and network-field visibility.

The older setConfigPortalTimeout(), setSaveConnect(), setShowStaticFields(), and related methods remain available. Prefer a single vocabulary within a product; the portal-prefixed methods make the policy visible in the portal's structured model.

Structured content

Use portalAddParameter() for editable product settings, portalAddInfoSection() for labelled read-only values, and portalAddHomeCard() for overview text or key/value cards. Parameters remain application-owned; information sections and cards are copied when registered.

See Portal content for the full persistence, validation, callback, and lifetime rules. The buildable Custom Portal Content example shows all three content types.

Supported boundary

There is no arbitrary HTML shell, route replacement, navigation injection, raw stylesheet, or script hook. Product branding and policy configure documented built-in functionality rather than private markup. If a product needs a new portal capability, add a narrow WiFiManager contract and test it on both supported targets.

Back to the documentation index or project overview.

6.7 KiB Raw Blame History