TypeScript port of ZXing multi-format 1D/2D barcode image processing library
TypeScript port of the ZXing multi-format 1D/2D barcode image processing library. Provides comprehensive barcode decoding (reading) and encoding (writing) capabilities for 17 different barcode formats with support for both browser and Node.js environments.
npm install @zxing/libraryimport {
MultiFormatReader,
BinaryBitmap,
HybridBinarizer,
RGBLuminanceSource
} from '@zxing/library';
const luminanceSource = new RGBLuminanceSource(imagePixels, width, height);
const binaryBitmap = new BinaryBitmap(new HybridBinarizer(luminanceSource));
const reader = new MultiFormatReader();
try {
const result = reader.decode(binaryBitmap);
console.log('Decoded:', result.getText());
console.log('Format:', result.getBarcodeFormat());
} catch (error) {
console.error('No barcode found:', error);
}import {
QRCodeWriter,
BarcodeFormat,
EncodeHintType,
QRCodeDecoderErrorCorrectionLevel
} from '@zxing/library';
const writer = new QRCodeWriter();
const hints = new Map();
hints.set(EncodeHintType.ERROR_CORRECTION, QRCodeDecoderErrorCorrectionLevel.H);
const bitMatrix = writer.encode(
'https://example.com',
BarcodeFormat.QR_CODE,
300,
300,
hints
);
// Render: matrix.get(x, y) returns true for black pixelsimport { BrowserMultiFormatReader } from '@zxing/library';
const codeReader = new BrowserMultiFormatReader();
const videoElement = document.getElementById('video') as HTMLVideoElement;
const result = await codeReader.decodeOnceFromVideoDevice(undefined, videoElement);
console.log('Scanned:', result.getText());
codeReader.reset(); // Release camera| Format | Read | Write | Description |
|---|---|---|---|
| QR Code | ✓ | ✓ | Square matrix, 21×21 to 177×177 modules, 4 error correction levels |
| Data Matrix | ✓ | ✓ | Square/rectangular, ECC200, 10×10 to 144×144 modules |
| Aztec | ✓ | ✓ | Bulls-eye center, compact (1-4 layers) or full (1-32 layers) |
| PDF417 | ✓ | ✗ | Stacked linear, 3-90 rows, 9 error correction levels |
| MaxiCode | ✗ | ✗ | Fixed size, circular finder (not implemented) |
| Format | Read | Write | Description |
|---|---|---|---|
| EAN-13 | ✓ | ✗ | 13 digits, retail products worldwide |
| EAN-8 | ✓ | ✗ | 8 digits, small packages |
| UPC-A | ✓ | ✗ | 12 digits, North American retail |
| UPC-E | ✓ | ✗ | 8 digits, zero-suppressed UPC-A |
| Code 128 | ✓ | ✗ | High-density alphanumeric, shipping/logistics |
| Code 39 | ✓ | ✗ | Alphanumeric + symbols, automotive/military |
| Code 93 | ✓ | ✗ | Compact alphanumeric, logistics |
| ITF | ✓ | ✗ | Numeric only, interleaved pairs, warehousing |
| Codabar | ✓ | ✗ | Numeric + symbols, libraries/blood banks |
| RSS-14 | ✓ | ✗ | 14-digit GTIN, compact for small items |
| RSS Expanded | ✓ | ✗ | Variable length with AIs (⚠️ experimental) |
class MultiFormatReader implements Reader {
decode(image: BinaryBitmap, hints?: Map<DecodeHintType, any>): Result;
decodeWithState(image: BinaryBitmap): Result;
setHints(hints: Map<DecodeHintType, any> | null): void;
reset(): void;
}
class QRCodeReader implements Reader {
decode(image: BinaryBitmap, hints?: Map<DecodeHintType, any>): Result;
reset(): void;
}
class DataMatrixReader implements Reader {
decode(image: BinaryBitmap, hints?: Map<DecodeHintType, any>): Result;
reset(): void;
}
class AztecCodeReader implements Reader {
decode(image: BinaryBitmap, hints?: Map<DecodeHintType, any>): Result;
reset(): void;
}
class PDF417Reader implements Reader, MultipleBarcodeReader {
decode(image: BinaryBitmap, hints?: Map<DecodeHintType, any>): Result;
decodeMultiple(image: BinaryBitmap, hints?: Map<DecodeHintType, any>): Result[];
reset(): void;
}class MultiFormatWriter implements Writer {
encode(
contents: string,
format: BarcodeFormat,
width: number,
height: number,
hints: Map<EncodeHintType, any>
): BitMatrix;
}
class QRCodeWriter implements Writer {
encode(
contents: string,
format: BarcodeFormat,
width: number,
height: number,
hints?: Map<EncodeHintType, any>
): BitMatrix;
}
class DataMatrixWriter implements Writer {
encode(
contents: string,
format: BarcodeFormat,
width: number,
height: number,
hints?: Map<EncodeHintType, any>
): BitMatrix;
}
class AztecCodeWriter implements Writer {
encode(
contents: string,
format: BarcodeFormat,
width: number,
height: number,
hints?: Map<EncodeHintType, any>
): BitMatrix;
}class BinaryBitmap {
constructor(binarizer: Binarizer);
getWidth(): number;
getHeight(): number;
getBlackRow(y: number, row: BitArray | null): BitArray;
getBlackMatrix(): BitMatrix;
isCropSupported(): boolean;
crop(left: number, top: number, width: number, height: number): BinaryBitmap;
}
abstract class LuminanceSource {
abstract getRow(y: number, row?: Uint8ClampedArray): Uint8ClampedArray;
abstract getMatrix(): Uint8ClampedArray;
abstract invert(): LuminanceSource;
getWidth(): number;
getHeight(): number;
}
class RGBLuminanceSource extends LuminanceSource {
constructor(
luminances: Uint8ClampedArray | Int32Array,
width: number,
height: number,
dataWidth?: number,
dataHeight?: number,
left?: number,
top?: number
);
}
class HybridBinarizer extends Binarizer {
constructor(source: LuminanceSource);
}class Result {
constructor(
text: string,
rawBytes: Uint8Array | null,
numBits: number,
resultPoints: ResultPoint[],
format: BarcodeFormat,
timestamp: number
);
getText(): string;
getRawBytes(): Uint8Array | null;
getBarcodeFormat(): BarcodeFormat;
getResultMetadata(): Map<ResultMetadataType, Object>;
getResultPoints(): ResultPoint[];
}| Hint | Type | Purpose |
|---|---|---|
POSSIBLE_FORMATS | BarcodeFormat[] | Limit to specific formats (improves performance) |
TRY_HARDER | boolean | More thorough scanning (slower, more accurate) |
PURE_BARCODE | boolean | Image contains only barcode (faster) |
CHARACTER_SET | string | Character encoding (e.g., "UTF-8") |
| Hint | Type | Purpose |
|---|---|---|
ERROR_CORRECTION | varies | QR: L/M/Q/H, Aztec: 0-100%, PDF417: 0-8 |
CHARACTER_SET | string | Character encoding |
MARGIN | number | Quiet zone size in pixels |
QR_VERSION | number | QR Code version 1-40 |
AZTEC_LAYERS | number | -4 to -1 (compact), 0 (auto), 1-32 (full) |
DATA_MATRIX_SHAPE | SymbolShapeHint | FORCE_SQUARE or FORCE_RECTANGLE |
See Real-World Scenarios and Edge Cases for complete examples of:
| Exception | Cause | Action |
|---|---|---|
NotFoundException | No barcode found | Check image quality, try TRY_HARDER |
ChecksumException | Too many errors | Retry with better image |
FormatException | Invalid structure | Check barcode not obscured |
WriterException | Encoding failed | Check data size/format |
try {
const result = reader.decode(bitmap);
} catch (error) {
if (error instanceof NotFoundException) {
// No barcode found
} else if (error instanceof ChecksumException) {
// Barcode damaged
}
}MultiFormatReader, MultiFormatWriter - auto-detect formatsLuminanceSource → Binarizer → BinaryBitmapCore APIs:
Format-Specific:
Utilities:
QR Code: General purpose, mobile apps, marketing, maximum compatibility
Data Matrix: Manufacturing, healthcare, electronics, small items
Aztec: Transport tickets, ID documents, high data density
PDF417: Driver licenses, shipping labels, inventory (decode only)
1D Barcodes: Retail products, inventory, legacy systems
const hints = new Map();
// Limit to specific formats (improves performance)
hints.set(DecodeHintType.POSSIBLE_FORMATS, [
BarcodeFormat.QR_CODE,
BarcodeFormat.EAN_13
]);
// Enable accuracy mode
hints.set(DecodeHintType.TRY_HARDER, true);
// Specify character encoding
hints.set(DecodeHintType.CHARACTER_SET, 'UTF-8');
// Pure barcode image (no detection needed, faster)
hints.set(DecodeHintType.PURE_BARCODE, true);const hints = new Map();
// QR Code: Set error correction level
hints.set(EncodeHintType.ERROR_CORRECTION, 'H'); // L, M, Q, or H
// Set character encoding
hints.set(EncodeHintType.CHARACTER_SET, 'UTF-8');
// Set margin/quiet zone
hints.set(EncodeHintType.MARGIN, 4); // In modules
// QR Code: Force specific version
hints.set(EncodeHintType.QR_VERSION, 10); // 1-40
// Aztec: Set layer count
hints.set(EncodeHintType.AZTEC_LAYERS, 0); // 0=auto, negative=compact, positive=full
// Data Matrix: Force square shape
hints.set(EncodeHintType.DATA_MATRIX_SHAPE, SymbolShapeHint.FORCE_SQUARE);Choose between two binarizers:
HybridBinarizer (recommended default):
GlobalHistogramBinarizer:
// Recommended (more accurate)
const binarizer = new HybridBinarizer(luminanceSource);
// Faster alternative
const binarizer = new GlobalHistogramBinarizer(luminanceSource);import {
NotFoundException,
FormatException,
ChecksumException,
WriterException
} from '@zxing/library';
try {
const result = reader.decode(bitmap);
// Success
} catch (error) {
if (error instanceof NotFoundException) {
// No barcode found - check image quality
} else if (error instanceof ChecksumException) {
// Barcode damaged - retry with TRY_HARDER
} else if (error instanceof FormatException) {
// Invalid barcode structure
} else if (error instanceof WriterException) {
// Encoding failed - check data size/format compatibility
}
}Deprecation: Browser-specific classes are moving to @zxing/browser package:
BrowserMultiFormatReader → Use from @zxing/browserBrowserQRCodeReader → Use from @zxing/browserBrowser* classes → Use from @zxing/browserCamera Requirements:
reset() to release camerasetHints() + decodeWithState() for batch processingPOSSIBLE_FORMATS hint when format is known| Format | Numeric | Alphanumeric | Binary |
|---|---|---|---|
| QR Code (v40, L) | 7,089 | 4,296 | 2,953 bytes |
| Data Matrix (144×144) | 3,116 | 2,335 | 1,555 bytes |
| Aztec (32 layers, 33% ECC) | ~3,800 | ~3,000 | ~1,500 bytes |
| PDF417 (max) | 2,710 | 1,850 | 1,108 bytes |
Install with Tessl CLI
npx tessl i tessl/npm-zxing--library@0.21.14