Skip to content

feat: add measurement units (mm, cm, in) for QR and 2D matrix SVG output #78

@productdevbook

Description

@productdevbook

Problem

Print is the primary use case for barcodes and QR codes — product labels, shipping labels, packaging, ID cards, etc. Developers working with print workflows need precise physical dimensions.

Currently in etiket:

  • 1D barcodes ✅ have unit option supporting px | mm | in | pt | cm (via BarcodeSVGOptions.unit)
  • QR codes ❌ only accept size in pixels (via QRCodeSVGOptions.size)
  • 2D matrices (DataMatrix, PDF417, Aztec) ❌ only accept size in pixels (via MatrixSVGOptions.size)

This inconsistency means:

// ✅ 1D barcode with physical units — works
barcode("123", { unit: "mm", height: 15, barWidth: 0.33 })

// ❌ QR code with physical units — not possible
qrcode("test", { size: 200 }) // 200... pixels? mm? no way to specify

// ❌ DataMatrix with physical units — not possible
datamatrix("test", { size: 200 }) // same problem

Ecosystem context

  • bwip-js supports physical units for all barcode types
  • Print specifications (GS1, ISO) define barcode sizes in mm
  • Swiss QR-bill spec requires 46mm × 46mm QR code
  • GS1 DataMatrix minimum size is 2mm × 2mm per module

Proposal

Add unit option to QRCodeSVGOptions and MatrixSVGOptions:

interface QRCodeSVGOptions {
  size?: number;
  unit?: "px" | "mm" | "in" | "pt" | "cm";  // NEW
  // ...existing options
}

interface MatrixSVGOptions {
  size?: number;
  unit?: "px" | "mm" | "in" | "pt" | "cm";  // NEW
  // ...existing options
}

Example output:

qrcode("test", { size: 46, unit: "mm" })
// → <svg ... width="46mm" height="46mm" viewBox="0 0 46 46">

datamatrix("test", { size: 20, unit: "mm" })
// → <svg ... width="20mm" height="20mm" viewBox="0 0 20 20">

Impact

  • Consistent API across all barcode types
  • Enables print-ready output without external conversion
  • Required for standards-compliant Swiss QR-bill generation (46mm × 46mm)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions