SigilUtilities

QR code generation and scanning: pure matrix encoder, SVG and canvas renderers, native BarcodeDetector scanning

Version

v26.10.0

Size

6.3 KB gzip

Dependencies

Zero dependencies

Runtime support

BrowserNode ≥22

Key exports

encodeQrtoSvgcreateQrScannerqrCapacitydetectQr

Works well with

mesh refine

Why Sigil?

QR workflows usually pull in a general-purpose barcode library that renders to canvas and guesses at colors, or a from-scratch decoder you do not need. Sigil is a pure, zero-dependency encoder (numeric, alphanumeric, and byte modes; versions 1–40; all four error-correction levels; automatic mask selection) with renderers that stay out of the way: an SVG string that themes with CSS, and a canvas painter for print/bitmap flows. Scanning is a thin lifecycle wrapper over the platform's native BarcodeDetector, so there is no decoder weight and no polyfill to ship.

// Before: a QR library per concern, canvas-only output, hardcoded colors
import QRCode from 'qrcode';
const dataUrl = await QRCode.toDataURL(text, { width: 256, color: { dark: '#000' } });
img.src = dataUrl; // raster, fixed colors, no theme support

// After: encode once, render anywhere
import { encodeQr, toSvg } from '@vielzeug/sigil';
const matrix = encodeQr(text); // smallest version that fits, auto mask
element.innerHTML = toSvg(matrix); // currentColor modules: themes with CSS

Feature	Sigil	qrcode (node-style)	jsqr
Bundle size	6.3 KB	~100 kB+	decoder only
Runtime dependencies	none		none
Output	Matrix, SVG string, canvas	Canvas/DataURL/UTF-8	N/A
Themeable output	currentColor by default	Hardcoded color strings	N/A
Scanning	Native BarcodeDetector wrapper		Pure-JS decoder
SSR-safe import

Use Sigil when you need QR output that themes with your UI (SVG/currentColor), a minimal encoder with no runtime dependencies, or a scanner that uses the platform decoder instead of shipping one.

Consider jsqr-style decoding when you must scan in browsers without BarcodeDetector: sigil reports SigilUnsupportedError rather than bundling a fallback decoder.

Installation

pnpm

pnpm add @vielzeug/sigil

npm

npm install @vielzeug/sigil

yarn

yarn add @vielzeug/sigil

Quick Start

Encode to an SVG string: works in Node and the browser:

import { encodeQr, qrCapacity, toSvg } from '@vielzeug/sigil';

const payload = 'https://vielzeug.dev';
const matrix = encodeQr(payload, { errorCorrection: 'M' });
document.querySelector('#qr').innerHTML = toSvg(matrix, { label: 'Vielzeug link' });

Scan with the camera (browser only: see support notes in the usage guide):

import { createQrScanner } from '@vielzeug/sigil';

const video = document.querySelector('video');
const scanner = createQrScanner({ video });
scanner.onResult((result) => {
  console.log('scanned:', result.value); // once: true stops after first decode
});
await scanner.start(); // throws SigilUnsupportedError / SigilPermissionError

Features

• encodeQr: pure matrix encoder: numeric/alphanumeric/byte modes, versions 1–40, EC levels L/M/Q/H, automatic or forced mask
• qrCapacity: byte capacity per version/mode/level, for pre-flight validation
• toSvg: compact path-merged SVG string; currentColor modules, <title> + role="img" built in
• drawToCanvas: bitmap rendering with DPR-aware scaling for print and download flows
• detectQr: one-shot detection on any ImageBitmapSource
• createQrScanner: camera scan loop with once mode, status events, tap() observability, and strict disposal
• isQrScanSupported/qrScanSupport: sync and async feature detection that never assumes

Documentation

• Usage Guide: encoding modes, capacity, rendering, scanning, and testing
• API Reference: every export, option, type, and error
• Examples: copy-paste recipes, including pairing two devices with meshQrCodec

See Also

• Mesh: backendless P2P sessions; meshQrCodec produces compact QR-friendly pairing payloads
• Refine: ore-qr-code and ore-qr-scanner wrap sigil in ready-made, themeable components