@qr-plus/wifi

WiFi QR code string builder with validation. Generates properly formatted WiFi configuration strings following the ZXing standard.

Features

• Standard-compliant — Follows the WIFI: URI scheme used by Android and iOS 11+
• Validated — SSID presence, password requirements, encryption type validation
• Escaped — Handles special characters (;, :, ,, ", \) in SSID and password
• Typed — Full TypeScript types with const-based enums
• Zero dependencies — No runtime dependencies
• Framework agnostic — Works with any QR code generator

Installation

npm install @qr-plus/wifi

Quick Start

import { buildWifiString } from "@qr-plus/wifi";

const content = buildWifiString({
  ssid: "MyNetwork",
  password: "super-secret",
  encryption: "WPA",
});
// => "WIFI:T:WPA;S:MyNetwork;P:super-secret;;"

Usage with @qr-plus/core

import { buildWifiString } from "@qr-plus/wifi";
import { renderToSVG } from "@qr-plus/core";

const svg = renderToSVG(
  buildWifiString({
    ssid: "MyNetwork",
    password: "super-secret",
  })
);

Usage with @qr-plus/react

import { buildWifiString } from "@qr-plus/wifi";
import { QRCode } from "@qr-plus/react";

function WifiQR() {
  const content = buildWifiString({
    ssid: "GuestWiFi",
    password: "welcome123",
  });

  return <QRCode value={content} />;
}

API

buildWifiString(config: WifiConfig): string

Builds a WiFi QR code content string from a configuration object.

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | ssid | string | ✅ | — | Network name (SSID) | | password | string | For WPA/WEP | — | Network password | | encryption | WifiEncryption | — | "WPA" | Encryption type | | hidden | boolean | — | false | Whether the network is hidden |

Encryption types

| Constant | Value | Description | |----------|-------|-------------| | WIFI_ENCRYPTION.WPA | "WPA" | WPA/WPA2/WPA3 (recommended) | | WIFI_ENCRYPTION.WEP | "WEP" | WEP (legacy) | | WIFI_ENCRYPTION.NONE | "nopass" | Open network |

Examples

WPA network (default)

buildWifiString({
  ssid: "MyNetwork",
  password: "super-secret",
});
// => "WIFI:T:WPA;S:MyNetwork;P:super-secret;;"

Hidden network

buildWifiString({
  ssid: "HiddenNet",
  password: "pass123",
  hidden: true,
});
// => "WIFI:T:WPA;S:HiddenNet;P:pass123;H:true;;"

Open network

import { WIFI_ENCRYPTION } from "@qr-plus/wifi";

buildWifiString({
  ssid: "FreeWiFi",
  encryption: WIFI_ENCRYPTION.NONE,
});
// => "WIFI:T:nopass;S:FreeWiFi;;"

Special characters

buildWifiString({
  ssid: "My;Network",
  password: "p:ass",
});
// => "WIFI:T:WPA;S:My\;Network;P:p\:ass;;"

Error Handling

The function throws WifiError with specific error codes:

| Code | Condition | |------|-----------| | EMPTY_SSID | SSID is empty or whitespace-only | | PASSWORD_REQUIRED | Password missing for WPA or WEP encryption | | INVALID_ENCRYPTION | Unrecognized encryption type |

import { buildWifiString, WifiError, WIFI_ERROR_CODE } from "@qr-plus/wifi";

try {
  buildWifiString({ ssid: "" });
} catch (error) {
  if (error instanceof WifiError) {
    console.log(error.code); // "EMPTY_SSID"
    console.log(error.message); // "SSID must be a non-empty string."
  }
}

Part of the @qr-plus ecosystem

| Package | Description | |---------|-------------| | @qr-plus/core | Zero-dependency QR code engine | | @qr-plus/react | React components and hooks | | @qr-plus/cli | Terminal QR code generator | | @qr-plus/wifi | WiFi QR string builder | | @qr-plus/vcard | vCard QR string builder |

License

MIT