📦 Chunked QR Code Library

A TypeScript + React library for splitting data into multiple QR codes, scanning them back (via camera or input), and reconstructing the original payload.

Designed for efficient transfer of large payloads with low metadata overhead and progress tracking.

Installation

npm install qr-chunker

🛠 Usage

1. Generate QR Codes

import { useQRGenerator } from "qr-chunker";

const { generateQRCodes } = useQRGenerator();

const qrChunks = generateQRCodes("Hello World!", 2); // split into 3 QR codes

Each qrChunk will contain:

interface QRChunk {
    id: string;        // session ID
    index: number;     // chunk index
    total: number;     // total number of chunks
    payload: Uint8Array; // compact binary payload with metadata
    data: Uint8Array;  // raw chunk data only
}

You can render with QRCode.toCanvas:

import QRCode from "qrcode";

function QRCodeDisplay({ data }: { data: Uint8Array }) {
  const canvasRef = React.useRef<HTMLCanvasElement>(null);

  React.useEffect(() => {
    if (canvasRef.current) {
      QRCode.toCanvas(canvasRef.current, [{ data, mode: 'byte' }], { errorCorrectionLevel: "M" });
    }
  }, [data]);

  return <canvas ref={canvasRef} />;
}

2. Scan QR Codes

import { useQRScanner } from "qr-chunker";

const {
  processScannedData,
  getProgress,
  getCompletedData,
  reset,
} = useQRScanner();

Process scanned QR code data:

const handleScan = (scannedData: Uint8Array) => {
  const result = processScannedData(scannedData);
  const progress = getProgress(result.sessionId);
  console.log(`Progress: ${progress.collected}/${progress.total}`);
};

Get completed data when all chunks are scanned:

const data = getCompletedData(sessionId);
if (data) {
  console.log(new TextDecoder().decode(data));
}

📂 Data Format

Each QR payload is a binary buffer:

[ MAGIC (2 bytes) | VERSION (1 byte) | SESSION_ID (4 bytes) |
  CHUNK_INDEX (2 bytes) | TOTAL_CHUNKS (2 bytes) | DATA... ]

🧪 Demo

The repo includes a demo app with:

• Generator tab → create QR codes from payloads
• Scanner tab → scan codes manually or via camera
• Real-time reconstruction progress bar

📜 License

MIT