@sdxc/qr

QR Code Model 2 encoder with optimal segmentation, SVG path data and a remix/component renderer.

Installation

npm add @sdxc/qr

The main entry point depends only on @sdxc/result and runs anywhere TextEncoder does: Workers, Bun, Node and the browser. @sdxc/qr/ui renders through remix/component; install remix to use it.

Usage

Encode text

import { QR } from "@sdxc/qr";
import { isSuccess } from "@sdxc/result";

let encoded = QR.encode("https://example.com/device?user_code=WDJB-MJHT");

if (isSuccess(encoded)) {
	encoded.data.version; // 4, the smallest version that holds the text
	encoded.data.size; // 33 modules a side
	encoded.data.level; // "Q": raised from the default "M" because the version had room
}

A string is split into numeric, alphanumeric and UTF-8 byte segments with the fewest total bits, so a URI around an upper-case token takes fewer modules than it would as bytes alone.

Render it with remix/component

import { QrCode } from "@sdxc/qr/ui";

<QrCode path={encoded.data.toSVGPath()} label="Scan to open this page on your phone" />;

QrCode takes path data, which is plain JSON, so the code that encodes decides what to render on failure and the component also works as a prop of a hydrated island.

Draw into your own markup

let { d, viewBox } = encoded.data.toSVGPath({ margin: 2 });
// <svg viewBox={viewBox}><rect width="100%" height="100%" fill="#fff" /><path d={d} /></svg>

Handle a failure

import { QR } from "@sdxc/qr";
import { isFailure } from "@sdxc/result";

let encoded = QR.encode(payload, { maxVersion: 10 });

if (isFailure(encoded)) {
	if (encoded.error.code === "too-long")
		encoded.error.bits; // { needed, available }
	else encoded.error.message; // which option was out of range
}

API

QR

One encoded symbol, with version (1–40), level (the level applied, after any boost), mask (0–7) and size (17 + 4 * version modules a side, quiet zone excluded). QR.encode is the only way to get one, so every instance holds a valid symbol.

QR.encode(data: string | Uint8Array, options?: QrOptions): Result<QR, QrTooLongError | QrOptionsError>

Encodes text or bytes as the smallest symbol that holds them. Text goes into byte segments as UTF-8; a Uint8Array is encoded as bytes as given.

• options.level: the minimum error correction level. Default "M".

• options.minVersion: the smallest version to try. Default 1.

• options.maxVersion: the largest version to try; data that does not fit fails with too-long. Default 40.

• options.mask: a fixed mask, 0–7. Omitted, every mask is scored and the lowest penalty wins.

• options.boostLevel: raises the level as far as the chosen version still holds the data, since the extra correction costs no modules. Default true.

qr.isDark(x: number, y: number): boolean

Whether a module is dark. Coordinates outside the symbol answer false, so a renderer draws the quiet zone by reading past the edge.

qr.toSVGPath(options?: SvgPathOptions): SvgPath

Path data for one <path>: each horizontal run of dark modules is one rectangle, one unit per module. viewBox and size include the quiet zone, whose width margin sets in modules (default 4, the standard's).

QrCode from @sdxc/qr/ui

An inline <svg role="img"> with a light background and one dark path. Its colors stay as given under dark and forced-color themes, since scanners need a dark code on a light margin; show the text the code carries beside it, because the payload stays out of the accessibility tree.

• path: path data from qr.toSVGPath(), quiet zone included.

• label: the accessible name, saying what the code is for.

• size: a CSS length for the rendered width and height. Default "12rem".

• dark: module color. Default "#000".

• light: background and quiet zone color. Default "#fff". A brand pair needs the same strong contrast.

• mix: mixins applied to the <svg>, after the component's own.

QrError

The Error every failure extends, with a code. Checking code narrows to the subclass.

QrTooLongError

Code too-long: the data does not fit maxVersion at level. bits holds { needed, available }.

QrOptionsError

Code invalid-options: a version outside 1–40, minVersion above maxVersion, a mask outside 0–7, or an unknown level.

Types

• QrLevel: "L" | "M" | "Q" | "H", recovering about 7%, 15%, 25% and 30% of codewords.

• QrOptions: the options of QR.encode.

• SvgPathOptions: { margin?: number }.

• SvgPath: { d: string; viewBox: string; size: number }.

• QrError.Code: "too-long" | "invalid-options".

• QrError.Bits: { needed: number; available: number }.

Pattern: An Authenticator Enrolment Page

Encode where a failure can be logged, and render the code above the setup key, which stays as the text alternative.

import { QR } from "@sdxc/qr";
import { QrCode } from "@sdxc/qr/ui";
import { isSuccess } from "@sdxc/result";
import type { Handle } from "remix/component";

function EnrolPage(handle: Handle<{ uri: string; setupKey: string; qr: QR | null }>) {
	return () => {
		let { uri, setupKey, qr } = handle.props;
		return (
			<main>
				<h1>Set up your authenticator app</h1>
				{qr && <QrCode path={qr.toSVGPath()} label="QR code for your authenticator app" />}
				<p>
					Or enter this key: <code>{setupKey}</code>
				</p>
				<a href={uri}>Open in an authenticator app on this device</a>
			</main>
		);
	};
}

let uri =
	"otpauth://totp/Acme:ada%40example.com?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Acme";
let encoded = QR.encode(uri);

let page = (
	<EnrolPage
		uri={uri}
		setupKey="JBSW Y3DP EHPK 3PXP"
		qr={isSuccess(encoded) ? encoded.data : null}
	/>
);

Pattern: Keeping A Code Small On Screen

Cap the version, and fall back to the link when the data needs more modules than the layout has room for.

import { QR } from "@sdxc/qr";
import { isFailure } from "@sdxc/result";

let encoded = QR.encode(url, { level: "L", maxVersion: 6 });

if (isFailure(encoded) && encoded.error.code === "too-long") {
	let { needed, available } = encoded.error.bits;
	let overBy = Math.ceil((needed - available) / 8);
	// Show the link alone, and shorten the URL by `overBy` bytes to fit a version 6 code
}

Pattern: A Printed Label That Survives Damage

A label on a box gets scuffed, so ask for level H and give it a wider quiet zone. Encode an identifier as bytes when it is not text.

import { QR } from "@sdxc/qr";
import { isSuccess } from "@sdxc/result";

let encoded = QR.encode(new TextEncoder().encode("PKG-000123"), { level: "H" });

if (isSuccess(encoded)) {
	let { d, viewBox } = encoded.data.toSVGPath({ margin: 6 });
	// <svg viewBox={viewBox} width="30mm" height="30mm"><path d={d} /></svg>
}

Pattern: Rendering In A Terminal

isDark answers false past the edge, so a loop that starts one module outside the symbol draws a quiet zone without bounds checks.

import { QR } from "@sdxc/qr";
import { isSuccess } from "@sdxc/result";

let encoded = QR.encode("https://example.com/pair?code=7F3K");

if (isSuccess(encoded)) {
	let qr = encoded.data;
	let lines: string[] = [];
	for (let y = -2; y < qr.size + 2; y++) {
		let line = "";
		for (let x = -2; x < qr.size + 2; x++) line += qr.isDark(x, y) ? "██" : "  ";
		lines.push(line);
	}
	process.stdout.write(lines.join("\n") + "\n");
}

Credits

The encoder follows the structure of Project Nayuki's MIT-licensed QR Code generator, itself written from ISO/IEC 18004, and its segmentation follows Nayuki's optimal segmentation algorithm.