A WiFi QR code is a QR image containing a structured text payload. When a compatible phone scans that payload, it can recognize the network name, security type, password, and hidden-network flag, then ask the user whether to join.
The image is usually easy to generate; most failures come from malformed payload text, missing escaping, low contrast, or insufficient testing. The following workflow uses the de facto WIFI format implemented by widely used QR readers and mobile cameras.
Understand the WIFI payload
A common password-protected network uses this structure. T is the authentication type, S is the SSID, P is the password, and the final double semicolon closes the payload.
| Field | Meaning | Example |
|---|---|---|
| T | Authentication type | WPA, WEP, WPA2-EAP, or nopass |
| S | Network SSID; required | Studio Network |
| P | Password; omit for nopass | correct-horse-battery-staple |
| H | Hidden SSID flag; optional | true |
WIFI:T:WPA;S:Studio Network;P:correct-horse-battery-staple;;Step 1: collect and classify the network details
Copy the SSID exactly, including capitalization and spaces. Confirm whether the network uses WPA-family security, WEP, enterprise authentication, or no password. If it is hidden, record that explicitly. Do not guess the security type from the password format.
- Prefer a guest network instead of exposing a primary household or office credential.
- Check whether captive-portal terms still appear after joining.
- Decide where the printed or displayed code will be visible.
- Plan a credential rotation date before distributing permanent signage.
Step 2: escape special characters
Backslash, semicolon, comma, double quote, and colon have structural meaning and should be escaped with a backslash when they occur inside values. Escaping is the most common reason a visually correct code produces a truncated password or wrong SSID.
SSID: Cafe;Guest\5G
Payload value: Cafe\;Guest\\5G
Password: tea:milk,2026
Payload value: tea\:milk\,2026Step 3: build the payload for your network type
Use one of these patterns, substituting escaped values. Field order is flexible, but consistent order makes manual review easier.
WPA network
WIFI:T:WPA;S:Studio Network;P:correct-horse-battery-staple;;
Open network
WIFI:T:nopass;S:Guest Lounge;;
Hidden WPA network
WIFI:T:WPA;S:Hidden Lab;P:sample-password;H:true;;Step 4: generate locally and choose robust visual settings
Paste the payload into a QR generator or use a structured WiFi form. Use a dark foreground on a light background, preserve a quiet zone around all four sides, and avoid decorative patterns that change the finder squares. More characters create a denser symbol and may require a larger image.
- Start with black on white for the most predictable result.
- Keep logos small and raise error correction only when decoration requires it.
- Export at a resolution appropriate to the final physical size.
- Do not screenshot a tiny preview and scale it up for print.
Step 5: verify the payload and real-world scan
Decode the exported QR file to confirm the exact text, then scan it from the expected distance on at least one iOS and one Android device when possible. Verify that the phone shows the intended SSID before accepting the connection prompt. Test the printed material, not just the source PNG on a bright monitor.
Troubleshooting WiFi QR codes
If scanning fails, separate image-recognition problems from payload problems. First decode the image as plain text. If decoding fails, increase size, contrast, and quiet zone. If the payload decodes but the phone does not offer to connect, compare every field and escape character.
| Symptom | Likely cause | Fix |
|---|---|---|
| No scanner recognizes the image | Low contrast, blur, crop, or dense output | Regenerate larger with a clear quiet zone |
| Text decodes but no join prompt appears | Invalid WIFI syntax or unsupported authentication | Check T, S, P, H, escapes, and terminator |
| SSID is truncated | Unescaped semicolon or backslash | Escape every structural character in the value |
| Correct payload joins the wrong network | Duplicate SSID nearby | Rename the guest SSID or verify before joining |
| Old device fails | Reader or authentication support differs | Provide the SSID and password as a text fallback |
Treat the QR code as a visible password
A WiFi QR code does not encrypt the password. Anyone who can photograph or decode the image can recover the payload. Use a guest network, isolate untrusted clients, restrict where the code is displayed, and replace both the sign and credential when access should end.
Key takeaways
A reliable WiFi QR code needs correct field syntax, complete escaping, clear artwork, and real-device testing. Build it from an isolated guest credential, verify both the decoded text and the join prompt, and remember that convenience does not make the embedded password confidential.