Zebra Printer Templating API 🏷️

Design beautiful labels for Zebra printers without the headache of cryptic ZPL commands. Use real-world measurements (inches/mm) instead of counting dots!

✨ Why Zebra Printer Templating API?

Writing raw ZPL code is painful. You have to:

Manually convert inches to dots based on printer DPI
Memorize cryptic commands like ^FO150,300^BCN,225,Y,N,A
Debug by trial and error
No type safety or autocomplete

Zebra Printer Templating API solves all of this:

// ❌ Old way (cryptic ZPL)
const zpl = '^XA^FO150,150^A0N,75,75^FDASSET TAG^FS^FO150,300^BCN,225,Y,N,A^FD12345^FS^XZ';

// ✅ New way (fluent & readable)
const zpl = new ZebraBuilder(300)
  .origin(0.5, 0.5)        // Position in inches
  .font('0', 0.25)         // Font with real height
  .text('ASSET TAG')
  .origin(0.5, 1.0)
  .barcode128('12345', 0.75)  // Barcode with readable height
  .render();

🚀 Quick Start

Installation

npm install zpl-fluent-api

Your First Label

import { ZebraBuilder } from 'zpl-fluent-api';

// Create a simple asset tag label
const zpl = new ZebraBuilder(300)  // 300 DPI printer
  .origin(0.5, 0.5)               // 0.5" from left, 0.5" from top
  .font('0', 0.25)                // Font 0, 0.25" height
  .text('ASSET TAG')
  .origin(0.5, 1.0)               // Move to next position
  .barcode128('12345', 0.75)      // Code 128 barcode, 0.75" height
  .render();

console.log(zpl);
// Output: ^XA^FO150,150^A0N,75,75^FDASSET TAG^FS^FO150,300^BCN,225,Y,N,A^FD12345^FS^XZ

Preview in Browser

const previewUrl = new ZebraBuilder(300)
  .origin(0.5, 0.5)
  .font('0', 0.25)
  .text('ASSET TAG')
  .origin(0.5, 1.0)
  .barcode128('12345', 0.75)
  .preview();

console.log(`Open this URL to preview: ${previewUrl}`);
// Opens Labelary viewer in your browser!

📚 Features

🎯 DPI-Aware - Automatic conversion from inches/mm to printer dots
🔗 Fluent Interface - Chain methods for intuitive label design
🛡️ Type Safety - Full TypeScript support with comprehensive types
✅ Validation - Built-in text validation for ZPL compatibility
👁️ Preview Integration - Instant browser preview via Labelary
🏭 Production Ready - Comprehensive error handling
📊 37+ ZPL Commands - All major template-building commands
🔢 10+ Barcode Types - Code 128, Code 39, QR, Data Matrix, Aztec, EAN, UPC, and more
🎨 Advanced Graphics - Boxes, circles, ellipses, diagonal lines, and images
⚙️ Label Configuration - Length, width, quantity, orientation, and more

📖 API Reference

Constructor

new ZebraBuilder(dpi?: number)

Parameters:

dpi - Printer DPI (dots per inch). Default: 203

Common DPI values:

150 (6 dpmm) - Low resolution
203 (8 dpmm) - Standard (default)
300 (12 dpmm) - High resolution
600 (24 dpmm) - Ultra high resolution

📍 Positioning & Text

`origin(x, y, unit?)`

Sets the field position (ZPL ^FO command).

.origin(1.0, 2.0)           // 1" from left, 2" from top
.origin(25, 50, 'mm')       // 25mm from left, 50mm from top

`font(name, height, unit?, width?, orientation?)`

Sets font properties (ZPL ^A command).

.font('0', 0.25)                    // Font 0, 0.25" height
.font('A', 12, 'mm')                // Font A, 12mm height
.font('0', 0.3, 'in', 0.25, 'R')    // Font 0, 0.3" height × 0.25" width, rotated 90°

`text(content)`

Adds text content (ZPL ^FD command).

.text('Hello World')        // Normal text

`fieldPosition(x, y, unit?)`

Alternative field positioning (ZPL ^FT command).

.fieldPosition(1.0, 2.0)     // 1" from left, 2" from top

🔢 Barcodes

`barcode128(data, height, opts?)`

Code 128 barcode (ZPL ^BC command).

.barcode128('123456789', 0.75)                    // Standard
.barcode128('ABC123', 15, 'mm', { printText: false })  // No text
.barcode128('DATA', 0.5, 'in', { printText: true, textAbove: true })

`barcode39(data, height, opts?)`

Code 39 barcode (ZPL ^B3 command).

.barcode39('ABC123', 0.5)                    // Standard
.barcode39('DATA', 15, 'mm', { printText: false })
.barcode39('DATA', 0.5, 'in', { checkDigit: true })

`qr_code(data, opts?)`

QR Code (ZPL ^BQ command).

.qr_code('https://example.com')                    // Standard
.qr_code('DATA', { magnification: 3, errorCorrection: 'H' })

`dataMatrix(data, height, opts?)`

Data Matrix (ZPL ^BX command).

.dataMatrix('DATA123', 100, { unit: 'dots', qualityLevel: 200 })

`aztec(data, opts?)`

Aztec barcode (ZPL ^BO command).

.aztec('DATA123', { magnification: 5 })

`barcode93(data, height, opts?)`

Code 93 barcode (ZPL ^BA command).

.barcode93('ABC123', 0.5)

`interleaved2of5(data, height, opts?)`

Interleaved 2 of 5 (ZPL ^BD command).

.interleaved2of5('12345', 0.75)

`ean13(data, height, opts?)`

EAN-13 barcode (ZPL ^BE command).

.ean13('123456789012', 0.75)

`upcA(data, height, opts?)`

UPC-A barcode (ZPL ^BU command).

.upcA('123456789012', 0.75)

`codabar(data, height, opts?)`

Codabar barcode (ZPL ^BK command).

.codabar('A123456B', 0.5)

🎨 Shapes & Graphics

`box(width, height, opts?)`

Draws a box/rectangle (ZPL ^GB command).

.box(4, 2)                           // 4" × 2" box
.box(100, 50, { unit: 'mm', thickness: 3 })
.box(2, 1, { unit: 'in', color: 'B', rounding: 3 })

`diagonalLine(xEnd, yEnd, opts?)`

Draws a diagonal line (ZPL ^GD command).

.diagonalLine(100, 100)                    // Diagonal line
.diagonalLine(50, 75, { unit: 'mm', thickness: 2, color: 'W' })

`circle(diameter, opts?)`

Draws a circle (ZPL ^GC command).

.circle(50)                                // 50" diameter
.circle(25, { unit: 'mm', thickness: 2, color: 'W' })

`ellipse(horizontalDiameter, verticalDiameter, opts?)`

Draws an ellipse (ZPL ^GE command).

.ellipse(100, 50)                          // 100" × 50" ellipse
.ellipse(50, 25, { unit: 'mm', thickness: 2 })

`graphicField(data, width, height, format?)`

Graphic field from hex data (ZPL ^GF command).

.graphicField('48484848484848', 10, 10)     // ASCII hex
.graphicField('DATA', 10, 10, 'B')          // Binary format

`recallGraphic(name, x, y, unit?)`

Recall stored graphic (ZPL ^XG command).

.recallGraphic('LOGO', 0.5, 0.5)

⚙️ Configuration

`labelLength(length, unit?)`

Sets label length (ZPL ^LL command).

.labelLength(4, 'in')              // 4 inch label
.labelLength(100, 'mm')            // 100mm label

`labelWidth(width, unit?)`

Sets label width (ZPL ^PW command).

.labelWidth(6, 'in')               // 6 inch width

`printQuantity(quantity, opts?)`

Sets print quantity (ZPL ^PQ command).

.printQuantity(10)                 // Print 10 labels
.printQuantity(5, { copies: 2, pause: 500 })

`printOrientation(orientation?)`

Changes print orientation (ZPL ^PO command).

.printOrientation('I')             // Invert orientation
.printOrientation('N')             // Normal

`mirror(enabled?)`

Mirrors label output (ZPL ^PM command).

.mirror(true)                      // Mirror label
.mirror(false)                     // Normal

`characterEncoding(encoding, sourceEncoding?)`

Sets character encoding (ZPL ^CI command).

.characterEncoding(28)             // UTF-8
.characterEncoding(28, 850)        // UTF-8 with CP-850 source

`defaultFont(name, height, opts?)`

Sets default font (ZPL ^CF command).

.defaultFont('0', 30, { unit: 'mm', width: 25, orientation: 'R' })

`defaultOrientation(orientation?)`

Sets default field orientation (ZPL ^FW command).

.defaultOrientation('N')           // Normal
.defaultOrientation('R')           // Rotated 90°

🔧 Field Options

`fieldReverse()`

Reverses field colors (ZPL ^FR command).

.fieldReverse()                    // White text on black

`fieldBlock(width, maxLines, secondaryParameter, justification, hangingIndent)`

Multi-line text block (ZPL ^FB command).

.fieldBlock(200, 5, 0, 'L', 0)

`fieldNumber(fieldNumber, opts?)`

Named field (ZPL ^FN command).

.fieldNumber(1)
.fieldNumber(2, { formatNumber: 100 })

`fieldVariable(fieldNumber, opts?)`

Variable field (ZPL ^FV command).

.fieldVariable(1)

`fieldExtraction(sourceField, startPosition, length, opts?)`

Data extraction (ZPL ^FE command).

.fieldExtraction(1, 0, 10)

`escapeCharacter(escape)`

Sets escape character (ZPL ^FH command).

.escapeCharacter('_')              // Use underscore as escape

`fieldHex()`

Enables hex mode (ZPL ^FH command).

.fieldHex()

`comment(text)`

Adds comment (ZPL ^FX command).

.comment('This is a comment')

🏷️ Label Settings

`labelHome(x, y)`

Sets label home position (ZPL ^LH command).

.labelHome(10, 10)

`labelShift(shift)`

Shifts label position (ZPL ^LS command).

.labelShift(10)

`mediaTracking(mode?)`

Sets media tracking (ZPL ^MN command).

.mediaTracking('A')                // Advanced tracking
.mediaTracking('N')                // No tracking

`barcodeDefaults(moduleWidth, opts?)`

Sets barcode defaults (ZPL ^BY command).

.barcodeDefaults(3, { wideToNarrowRatio: 2.5, height: 80 })

`downloadFormat(name, data)`

Downloads format to memory (ZPL ^DF command).

.downloadFormat('TEMPLATE', '^XA^FO100,100^FDTEMPLATE^FS^XZ')

`recallFormat(name)`

Recalls format from memory (ZPL ^XF command).

.recallFormat('TEMPLATE')

🛠️ Utility Methods

`render()`

Returns the complete ZPL code.

const zpl = builder.render();

`preview(labelWidth?, labelHeight?)`

Generates a Labelary preview URL.

const url = builder.preview();              // Default 4×6 inch
const url = builder.preview(3, 2);         // 3×2 inch label

`getDPI()`

Returns the current DPI setting.

const dpi = builder.getDPI(); // 300

`getCurrentPosition()`

Returns current position in dots.

const pos = builder.getCurrentPosition(); // {x: 150, y: 300}

💡 Examples

🏷️ Product Label

const productLabel = new ZebraBuilder(300)
  .characterEncoding(28)                    // UTF-8 encoding
  .barcodeDefaults(2, { wideToNarrowRatio: 3, height: 80 })
  .box(2, 1, { thickness: 3 })              // Border box
  .origin(0.1, 0.1)
  .defaultFont('0', 0.12, { unit: 'in' })
  .text('PRODUCT')
  .origin(0.1, 0.3)
  .qr_code('https://example.com/product/123', { magnification: 4, errorCorrection: 'M' })
  .origin(0.1, 0.5)
  .barcode39('ABC123', 0.4, { unit: 'in', printText: true, checkDigit: true })
  .origin(1.5, 0.8)
  .font('0', 0.15, { unit: 'in', width: 0.15, orientation: 'R' })
  .fieldReverse()
  .text('$29.99')
  .printQuantity(1)
  .comment('End of label')
  .render();

📊 Multi-Barcode Label

const multiBarcodeLabel = new ZebraBuilder(203)
  .origin(0.25, 0.25)
  .font('0', 0.15)
  .text('MULTI-BARCODE EXAMPLE')
  .origin(0.25, 0.5)
  .qr_code('https://example.com', { magnification: 3, errorCorrection: 'H' })
  .origin(0.25, 1.0)
  .dataMatrix('DATA123', 100, { unit: 'dots', qualityLevel: 200, columns: 24, rows: 24 })
  .origin(0.25, 1.5)
  .aztec('AZTEC123', { magnification: 5, eci: true, size: 15 })
  .origin(0.25, 2.0)
  .circle(50, { thickness: 2 })
  .render();

🎨 Graphic-Intensive Label

const graphicLabel = new ZebraBuilder(300)
  .box(4, 3, { thickness: 3 })
  .origin(0.1, 0.1)
  .circle(30, { thickness: 2 })
  .origin(0.5, 0.1)
  .diagonalLine(100, 50, { thickness: 2 })
  .origin(0.1, 0.5)
  .font('0', 0.12)
  .fieldReverse()
  .text('GRAPHIC LABEL')
  .origin(0.1, 0.8)
  .font('0', 0.08)
  .text('with shapes and graphics')
  .origin(0.1, 1.2)
  .graphicField('48484848484848', 20, 10)
  .origin(0.1, 1.8)
  .barcode128('GRAPHIC123', 0.5)
  .mirror(true)
  .render();

📏 Metric Units

const metricLabel = new ZebraBuilder(203)
  .origin(10, 10, 'mm')      // 10mm from edges
  .font('0', 5, { unit: 'mm' })
  .text('METRIC LABEL')
  .origin(10, 20, 'mm')
  .barcode128('987654321', 15, { unit: 'mm' })
  .box(90, 50, { unit: 'mm', thickness: 2 })
  .render();

🏪 Retail Label with EAN-13

const retailLabel = new ZebraBuilder(300)
  .origin(0.25, 0.25)
  .font('0', 0.2)
  .text('PREMIUM COFFEE')
  .origin(0.25, 0.5)
  .ean13('123456789012', 0.75, { printText: true })
  .origin(0.25, 1.0)
  .font('0', 0.15)
  .text('$12.99')
  .origin(2.5, 0.5)
  .qr_code('https://shop.example.com/coffee', { magnification: 5 })
  .render();

🎯 DPI Support

The library automatically converts your measurements to dots based on your printer's DPI:

DPI	dpmm	Use Case
150	6	Low resolution, draft printing
203	8	Standard thermal printers (default)
300	12	High resolution, detailed labels
600	24	Ultra high resolution, small text

// All of these produce the same physical size on their respective printers
new ZebraBuilder(203).origin(1, 1)     // 203 dots
new ZebraBuilder(300).origin(1, 1)     // 300 dots
new ZebraBuilder(600).origin(1, 1)     // 600 dots

⚠️ Error Handling

The library includes built-in validation to catch common mistakes:

try {
  const builder = new ZebraBuilder(300);
  builder.text('Valid text');
  const zpl = builder.render();
} catch (error) {
  console.error('ZPL Error:', error.message);
}

Common errors caught:

Invalid DPI values
Unsupported characters in text
Invalid orientation values

👁️ Browser Preview

The preview() method generates URLs that work with Labelary's online ZPL viewer:

const url = builder.preview();
// Opens: http://labelary.com/viewer.html?zpl=^XA^FO100^FDHello^FS^XZ

// Custom label size
const customUrl = builder.preview(3, 2);  // 3×2 inch label

Just open the URL in your browser to see your label rendered instantly!

🛡️ TypeScript Support

Full TypeScript definitions included for excellent autocomplete and type safety:

import { ZebraBuilder } from 'zpl-fluent-api';

const builder: ZebraBuilder = new ZebraBuilder(300);
const url: string = builder.preview();

All options interfaces are fully typed:

const opts: Barcode128Options = {
  printText: true,
  textAbove: false,
  orientation: 'N',
  checkDigit: false,
  mode: 'A'
};

🤝 Contributing

We welcome contributions! Here's how to help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Add tests for new functionality
Ensure all tests pass (npm test)
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built for developers who love clean, readable code
Inspired by the need to make ZPL accessible to everyone
Thanks to Zebra Technologies for the ZPL specification

📞 Support

Made with ❤️ for label designers everywhere

Name		Name	Last commit message	Last commit date
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
test-badge.js		test-badge.js
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Zebra Printer Templating API 🏷️

✨ Why Zebra Printer Templating API?

🚀 Quick Start

Installation

Your First Label

Preview in Browser

📚 Features

📖 API Reference

Constructor

📍 Positioning & Text

origin(x, y, unit?)

font(name, height, unit?, width?, orientation?)

text(content)

fieldPosition(x, y, unit?)

🔢 Barcodes

barcode128(data, height, opts?)

barcode39(data, height, opts?)

qr_code(data, opts?)

dataMatrix(data, height, opts?)

aztec(data, opts?)

barcode93(data, height, opts?)

interleaved2of5(data, height, opts?)

ean13(data, height, opts?)

upcA(data, height, opts?)

codabar(data, height, opts?)

🎨 Shapes & Graphics

box(width, height, opts?)

diagonalLine(xEnd, yEnd, opts?)

circle(diameter, opts?)

ellipse(horizontalDiameter, verticalDiameter, opts?)

graphicField(data, width, height, format?)

recallGraphic(name, x, y, unit?)