QR Codes for Developers: Everything Behind That Black-and-White Square

1. What a QR Code Actually Encodes

QR (Quick Response) codes were invented in 1994 by Denso Wave for tracking car parts in Toyota factories. The standard is ISO/IEC 18004. A QR code is not a barcode — it's a 2D matrix that can encode up to ~3KB of data in multiple formats.

The data capacity varies dramatically by what you encode:

2. The Anatomy of a QR Code

Every QR code contains fixed structural elements that don't carry data:

• Finder patterns: The three large squares in corners. Scanners use these to locate and orient the code at any angle.
• Alignment patterns: Smaller squares inside the code (only in version 2+). Help correct for image distortion.
• Timing patterns: Alternating black/white lines that define the grid spacing.
• Format information: Encodes error correction level and mask pattern — stored twice for redundancy.
• Quiet zone: The mandatory white border of 4 modules around the code. Skipping this is the #1 cause of scan failures.

3. Error Correction: The Remarkable Part

QR codes use Reed-Solomon error correction, the same algorithm used in CDs and QR codes can recover even if part of the image is damaged, obscured, or (in branded QRs) replaced with a logo.

There are four levels:

4. Versions and Sizing

QR codes have 40 versions. Version 1 is a 21×21 matrix; each version adds 4 modules per side, so version 40 is 177×177. The version is selected automatically based on data length + error correction level.

A common mistake: embedding a long URL and using H error correction on a very small printout. The version jumps to 10+ and the modules become too tiny to scan with most phone cameras. For printed marketing materials, either shorten your URL or reduce error correction to M.

5. Generating QR Codes Correctly in Code

JavaScript / Node.js

// npm install qrcode
import QRCode from 'qrcode';

// Generate as SVG string (scalable, no pixelation)
const svg = await QRCode.toString('upi://pay?pa=merchant@bank&pn=Store&cu=INR', {
    type: 'svg',
    errorCorrectionLevel: 'M',   // L/M/Q/H
    margin: 4,                    // Quiet zone in modules
    color: {
        dark: '#000000',
        light: '#ffffff'
    }
});

// Generate as PNG buffer (for saving to disk or S3)
const buffer = await QRCode.toBuffer('https://tools-hut.com', {
    type: 'png',
    width: 400,                  // Pixel size of output
    errorCorrectionLevel: 'H'   // Use H if embedding logo
});

Python

# pip install qrcode[pil]
import qrcode
from PIL import Image

qr = qrcode.QRCode(
    version=None,                          # auto-select version
    error_correction=qrcode.constants.ERROR_CORRECT_H,
    box_size=10,
    border=4,
)
qr.add_data('https://tools-hut.com/tools/qr-code-generator.html')
qr.make(fit=True)

img = qr.make_image(fill_color='black', back_color='white')
img.save('output.png')

6. Common Mistakes That Break Scannability

1. Missing quiet zone: The 4-module white border is mandatory. Printing a QR right to the edge of a sticker will cause scan failures.
2. Too low contrast: Light grey on white, dark red on black — QR scanners need high contrast. Test with ≥70% contrast ratio.
3. Encoding as JPEG: JPEG compression introduces artefacts in the sharp black-white transitions. Always use PNG or SVG for QR codes.
4. Special characters unencoded: Spaces, ampersands, and non-ASCII in URLs must be percent-encoded before being passed to the QR library — the library does not URL-encode for you.
5. Scaling raster images up: A 100×100 PNG scaled to 800×800 becomes blurry. Generate at target size or use SVG.
6. Dark background, white QR: Inverted QR codes are not guaranteed to scan in all readers. The standard expects dark modules on light background.

7. Dynamic vs. Static QR Codes

Static QR codes encode the destination directly. Change the destination and you need a new code.

Dynamic QR codes encode a short redirect URL (like qr.co/abc123). The destination is stored server-side and can be changed without reprinting. They also provide scan analytics.

For campaigns, signage, or anything printed at scale — use dynamic codes. For technical use (UPI, WiFi credentials, app deep links) — use static codes and encode directly.