etiket

Core Capabilities

• Zero dependencies: Pure ESM and edge-runtime compatible (Cloudflare Workers, Deno, Bun).
• TypeScript-first: Strict types (TypeScript 7).
• Tree-shakeable: Sub-path exports allow for minimal bundle sizes.
• Output Formats: Generates SVG strings (no DOM required) and PNG raster output via etiket/png.
• Advanced Symbologies: Supports 1D barcodes (22 types), 2D codes (QR, Data Matrix, Aztec, PDF417), GS1 (including DataBar family), and 4-state postal barcodes.
• QR Customization: Supports 12 dot styles, corner styling, and automatic EC (Error Correction) upgrade to 'H' when a logo is present.
• Print Ready: Supports measurement units like px, mm, in, cm, and pt. Supports CSS currentColor for theme-aware rendering.

HIBC (Health Industry Bar Code, ANSI/HIBC 2.6) is a data format, not a symbology. It defines how to structure data like labeller codes, product numbers, expiry, and lot numbers.

To create a physical barcode, you must first use etiket's HIBC functions to generate the formatted string, and then pass that string to a barcode generator like barcode() (for Code 128 or Code 39) or datamatrix().

Modes 2 and 3 are used for parcel carrier labels (like UPS) to pack a 60-bit primary message (postal code, country, and service class) ahead of the secondary message.

• Mode 2: Uses a numeric postcode. A 5-digit US ZIP (country 840) is zero-filled to 9 digits. The postcode must be 1–9 digits.
• Mode 3: Uses an alphanumeric postcode (1–6 characters from A-Z, space, and ASCII range " to :).

If the postalCode is malformed (e.g., non-numeric in Mode 2, or out-of-charset in Mode 3), the library will throw an InvalidInputError.

import { maxicode } from "etiket"

// US: numeric ZIP+4 (Mode 2)
maxicode("SHIPMENT 4711", {
  mode: 2,
  postalCode: "12345",
  countryCode: 840,
  serviceClass: 1,
})

// UK: alphanumeric postcode (Mode 3)
maxicode("PACKAGE", {
  mode: 3,
  postalCode: "SN34RD",
  countryCode: 826,
  serviceClass: 11,
})

QR codes require specific string formats (conventions) to trigger actions like joining a Wi-Fi network or opening a contact card. etiket provides payload helpers that build these convention-compliant strings and return a rendered SVG.

Each helper accepts the same options as qrcode() as its last argument (QRCodeSVGOptions & QRCodeOptions), allowing you to control styling, error correction level (ecLevel), and sizing.

import { url } from "etiket"

// The helper returns a rendered SVG string
url("https://example.com", { size: 320, ecLevel: "H", dotType: "rounded" })

The RasterData object provides a lightweight representation of the barcode/matrix pixels. It uses one byte per pixel, where 0 represents the background and 1 represents the foreground.

Note on performance: Rows are shared where they repeat (e.g., in 1D barcodes). Treat the rows array as read-only; mutating a single Uint8Array in the rows array can change multiple visible rows in the final image.

interface RasterData {
  width: number          // pixels
  height: number         // pixels
  rows: Uint8Array[]     // one row per pixel row; 0 = background, 1 = foreground
}

Input Format

• Allowed Characters: Uppercase A-Z and digits 0-9.
• Payload Composition: PostNL requires a specific concatenation of postcode, house number, and addition (padded out) with no separators. This composition is the user's responsibility.

Important Caveats

• No Check Character: KIX does not have a check character. A transcription error will result in a valid-looking barcode for the wrong address. Always validate the address upstream.
• Error Handling: Lowercase letters or punctuation will throw an InvalidInputError.
• No Framing: Because there are no start/stop bars, a KIX barcode is structurally different from an RM4SCC barcode even if they contain the same data. Ensure your scanner is configured specifically for KIX.
• Encoding Restriction: Do not use encodeBars() for postal types; KIX data is encoded in bar height, not width.

JAB Code (ISO/IEC 23634) is a polychrome symbology where modules carry color indices.

WARNING

Experimental — not conformant. The etiket JAB Code encoder is not ISO/IEC 23634 conformant. It uses an XOR parity scheme instead of LDPC codes, and its metadata/finder patterns differ from the spec. No conforming reader will decode these symbols. Use it only for layout experiments and visual mock-ups, not for production scanning.

When encoding data for Plessey, follow these constraints:

• Character Set: Only hexadecimal digits 0-9 and A-F are allowed. Input is case-insensitive.
• Check Digits: The symbology automatically appends two CRC check digits using the polynomial x⁸ + x⁷ + x⁶ + x⁵ + x³ + 1.
• Warning: Do not include check digits in your input string, as they will be treated as data and additional check digits will be appended on top of them.