Options & defaults
This page documents the per-symbology defaults the API applies when an inline barcode tag omits a slot, and the optional overrides authors can supply.
Default sizing
When width|height is omitted, the API applies per-symbology defaults that produce sensible inline rendering:
| Family | Default size (W × H, points) |
|---|---|
| 2D matrix square (QR, DataMatrix, Aztec, MaxiCode, HIBC-DM) | 120 × 120 |
| Micro QR | 80 × 80 |
| Rectangular Micro QR (rMQR) | 200 × 60 |
| PDF417 / HIBC-PDF417 | 300 × 60 |
| Micro PDF417 / HIBC-Micro PDF417 | 180 × 60 |
| Code 16k / Codablock-F / HIBC-Codablock-F | 250 × 80 |
| DotCode / Han Xin / Grid Matrix / UPN QR / HIBC-Aztec | 120 × 120 |
| Ultracode | 200 × 120 |
| 1D linear (Code 128, Code 39, Code 93, Code 11, Codabar, ITF-14, Inter25, HIBC-128, HIBC-39, GS1-128, ExtendedCode39, Telepen, LOGMARS, VIN) | 250 × 50 |
| Telepen Numeric / MSI Plessey / Code 2 of 5 family / Flattermarken | 200 × 50 |
| Retail GTIN (EAN-13, EAN-8, UPC-A, UPC-E) | 250 × 50 |
| Postal narrow (Postnet, Planet, Royal Mail, Australia Post, Korea Post, Japan Post, KIX) | 160 × 20 |
| USPS Intelligent Mail | 200 × 20 |
| Deutsche Post Leitcode / Identcode | 250 × 30 |
| GS1 DataBar Omn / Ltd | 180 × 30 |
| GS1 DataBar Expanded | 250 × 30 |
| GS1 DataBar Stacked Omn | 180 × 60 |
| GS1 DataBar Expanded Stacked | 250 × 80 |
| Pharmacode / Pharma 2-Track | 100 × 40 |
| Channel Code | 80 × 40 |
Author-supplied dimensions always override the defaults.
DataMatrix shape
DataMatrix supports both square and rectangular variants. The API infers shape from the requested dimensions:
W == H→ square DataMatrix (e.g.100|100)W != H→ rectangular variant (e.g.100|40)
No keyword needed.
Default quiet zones
Quiet zones (the white margin around a barcode that scanners need to detect symbol boundaries) default to the ISO minimum for each symbology family — wide enough that production scanners reliably detect symbol boundaries.
| Family | Horizontal × Vertical (in module multiples) |
|---|---|
| QR | 4 × 4 |
| DataMatrix / HIBC-DM | 1 × 1 |
| PDF417 / Micro PDF417 / Aztec / MaxiCode / DotCode / Grid Matrix / UltraCode / UPN QR / HIBC-Aztec / HIBC-PDF417 / HIBC-Micro PDF417 | 2 × 2 |
| Han Xin / Code 16k / Codablock-F / HIBC-Codablock-F | 4 × 4 |
| Micro QR / rMQR / HIBC-QR | 2 × 2 — 4 × 4 |
| 1D linear (Code 128, Code 39, Code 93, Code 11, Codabar, ITF-14, Inter25, HIBC-128, HIBC-39, GS1-128, ExtendedCode39, Telepen, LOGMARS, VIN) | 10 × 0 |
| Telepen Numeric / MSI Plessey / Code 2 of 5 / Flattermarken | 10 × 0 — 4 × 0 |
| EAN / UPC | 0 × 0 (intrinsic asymmetric zones already in symbology) |
| Postal | 2 × 0 |
| Pharmacode | 4 × 0 |
Vertical quiet zone is 0 for 1D codes — they have no top/bottom scan-line ambiguity, and adding vertical whitespace just shrinks the visible bar height. EAN/UPC apply 0 horizontal because the symbology already encodes intrinsic asymmetric zones (11 left + 7 right per ISO).
Overriding the quiet zone
Tighter values trade scannability for visual compactness. Only use after validating with your actual scanner mix.
{ "p": "[barcode, code128, DOC-2026-04521, 200|50, quiet=4]" }
Color overrides
Foreground and background colors can be overridden via additional slots:
| Pattern | Effect |
|---|---|
#hex | Foreground only (e.g. #1A1A2E) |
#fg|#bg | Foreground + background (e.g. #FFFFFF|#1A1A2E) |
{ "p": "Brand QR: [barcode, qrcode, https://docpayload.example, 80|80, #1A1A2E]" }
{ "p": "Inverse: [barcode, qrcode, https://docpayload.example, 80|80, #FFFFFF|#1A1A2E]" }
Inverse contrast warning — light-on-dark is technically valid for QR but unreliable on cheap retail scanners. Prefer dark-on-light for production.
Error handling
If the encoder rejects a payload (e.g. EAN-13 with the wrong digit count, ITF-14 longer than 13 digits), the document still generates — the offending barcode is replaced with an inline diagnostic placeholder showing the encoder's exact error message:
[barcode error: itf14 — Input too long (13 character maximum)]
This means a single bad payload never takes down a full document, and template authors see exactly what went wrong without log-diving. The placeholder is also written to the server log at warning level for ops visibility.
Validation hints
Common payload constraints by symbology — check these first when you see an error placeholder:
| Symbology | Payload rule |
|---|---|
| EAN-13 | Exactly 12 or 13 digits |
| EAN-8 | Exactly 7 or 8 digits |
| UPC-A | Exactly 11 or 12 digits |
| UPC-E | Exactly 6, 7, or 8 digits |
| ITF-14 | Exactly 13 or 14 digits |
| GS1-128 | Application Identifiers in [NN] brackets |
| GS1 DataBar Limited | Indicator must be 0 or 1 (first digit) |
| Codabar | Must start and end with A, B, C, or D |
| Code 11 | Digits and dashes only |
| Pharmacode | Numeric, 3 to 131070 |
| HIBC family | Payload starts with + (auto-prepended) |
| VIN | 17 alphanumeric (per ISO 3779) |
| RM4SCC / Royal Mail | Digits only in this implementation |
| Postnet / Planet | 5, 9, or 11 digits |