WiFiManager gives ESP8266 and ESP32 firmware a polished, self-hosted Wi-Fi setup experience. It reconnects to saved networks and opens a temporary captive portal when it cannot, so users can configure the device from any phone or browser without a cloud service or companion app.

See it on real hardware

WiFiManager provides a self-hosted setup portal for Wi-Fi and application settings without copying portal HTML into each firmware. See the detailed portal UI guide for supported branding and content APIs.

Start with a working portal

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

WiFiManager wifi;

void setup() {
    Serial.begin(115200);

    // Leave the temporary setup portal available for three minutes.
    wifi.setConfigPortalTimeout(180);

    // Reconnect to saved Wi-Fi, or open the setup portal when none works.
    wifi.autoConnect("Device Setup", "change-me");
}

void loop() {
    // Service portal requests and connection state without blocking firmware work.
    wifi.process();
}

When saved Wi-Fi is unavailable, autoConnect() starts the portal asynchronously. Call process() from every loop() iteration while it may be open. Flash Basic Portal to try this exact flow; its README gives the network name, password, portal address, and expected result after saving Wi-Fi.

Building a Home Assistant device?

WiFiManager remains a standalone provisioning library. If a device also needs persistent configuration, MQTT, Home Assistant discovery, OTA, mDNS, and an optional local web UI, see DeviceFramework, which integrates this portal as part of that larger device lifecycle.

Make it yours

const char kTitle[] PROGMEM = "Set up Temperature Monitor";
const char kBrand[] PROGMEM = "Example Devices";
const char kAccent[] PROGMEM = "#347a45";

void setup() {
    WiFiManagerPortalConfig portalUI;

    // Leave fields unset to keep WiFiManager's built-in portal values.
    portalUI.title = WiFiManagerPortalText::progmem(kTitle);
    portalUI.identityText = WiFiManagerPortalText::progmem(kBrand);

    // Theme values customise the built-in styles; they do not replace the portal.
    portalUI.theme.accent = WiFiManagerPortalText::progmem(kAccent);
    portalUI.theme.cornerRadiusPx = 10;

    wifi.setPortalConfig(portalUI);  // Apply before the portal starts.
    wifi.autoConnect("Device Setup");
}

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

The Branded Portal example includes a static SVG, accessible identity text, and a small semantic theme. Custom Portal Content shows the supported parameters, information sections, and home cards without replacing the portal shell.

What it provides

Captive Wi-Fi setup: starts an access point only when saved network credentials cannot connect.
Responsive portal: one small portal for Wi-Fi, application fields, information, actions, and firmware update flow.
Structured APIs: C++ configuration and a local JSON protocol for the built-in portal.
Product presentation: title, logo, tagline, and semantic colour tokens without copying the portal HTML.
Primary and fallback networks: an opt-in two-network controller backed by an application-provided store.
ESP8266 and ESP32 support: the package resolves its asynchronous web dependencies for the selected target.

Choose a guide

Goal	Guide
Understand library/application ownership and supported boundaries	Architecture
Get a device online or recover from missing Wi-Fi	Provisioning lifecycle
Brand or constrain the built-in portal	Portal UI and configuration
Add and persist application settings, status, or home cards	Portal content
Configure primary/fallback station profiles	Station profiles
Surface setup, offline, and connection state in firmware	Observability
Configure AP, station, scan, or reconnect behaviour	Network configuration
Look up a supported C++ method and its timing	API reference
Understand the built-in portal's local JSON protocol	Portal API
Follow deployment-oriented integration patterns	Recipes
Build or flash a complete example	Examples
Run documentation and board-free compile checks	Testing
Contribute to this fork or prepare a release	Development

Install

[common]
lib_deps =
    WiFiManager=https://github.com/alexhopeoconnor/WiFiManager.git#v3.2.5

The suffix after # is a Git ref. PlatformIO clones the repository and checks out that release tag; GitHub Release assets are unrelated. Arduino IDE users can install this repository as a library checkout.

See the documentation index, examples, release history, and licence.