⚠️ Early Stage Project (Alpha)

This project is in active development. The API is subject to significant breaking changes without notice. It is not recommended for production use until v1.0 is released.

Current Features

• Fluent API: Build labels step-by-step using method chaining (new ZebraLabel(...).text(...).barcode(...)).
• DPI-Aware: Correctly converts units for 152, 203, 300, or 600 dpi printers.
• Unit Conversion: Define element positions in mm (default), cm, in, or dots.
• Elements Supported:
  • .text(): Fixed-size text.
  • .resizableText(): Single-line text that shrinks to fit.
  • .fieldBlock(): Multi-line, wrapping, and aligned text.
  • .barcode(): Code 128 barcodes.
  • .box(): Boxes and lines.
• Global Setup: Configures label width, height, and charset (e.g., for ç or á).

Installation

bun add zebra-zpl-builder

(Note: The package is not yet published to NPM. This will be the command once it is.)

How to Use

The library uses a Fluent API. You instantiate the ZebraLabel class with your global settings and then chain methods to add elements.

import { ZebraLabel, type ZebraLabelOptions } from "zebra-zpl-builder";

const options: ZebraLabelOptions = {
  dpi: 203,
  width: { value: 425, unit: "dots" },
  height: { value: 254, unit: "dots" },
  defaultUnit: "dots",
  charset: 28,
};

const label = new ZebraLabel(options)
  .fieldBlock(
    "Big Product name that will break in two lines",
    { position: { x: 20, y: 20 }, size: 17, width: 400, maxLines: 2 }
  )
  .text("94924-0256", { position: { x: 20, y: 67 }, size: 17 })
  .box({ position: { x: 93, y: 100 }, w: 267, h: 67, stroke: 1 })
  .text("$ 9999", { position: { x: 123, y: 130 }, size: 23 })
  .text("99", { position: { x: 193, y: 130 }, size: 12 })
  .box({ position: { x: 227, y: 137 }, w: 100, h: 1, stroke: 1 })
  .text("$ 14000", { position: { x: 233, y: 130 }, size: 23 })
  .text("00", { position: { x: 310, y: 130 }, size: 12 })
  .barcode("210000983917", {
    position: { x: 60, y: 180 },
    height: 47,
    readable: true,
  });
const zplString = label.generate();

console.log(zplString);

Resulting ZPL Output

The code above will generate the following ZPL string, ready to be sent to a printer:

^XA
^CI28
^LH0,0
^PW425
^LL254
^A0N,17,17
^FO20,20
^FB400,2,0,L,0
^FDBig Product name that will break in two linesFS
^A0N,17,17
^FO20,67
^FD94924-0256^FS
^FO93,100
^GB267,67,1,B,0^FS
^A0N,23,23
^FO123,130
^FD$ 9999^FS
^A0N,12,12
^FO193,130
^FD99^FS
^FO227,137
^GB100,1,1,B,0^FS
^A0N,23,23
^FO233,130
^FD$ 14000^FS
^A0N,12,12
^FO310,130
^FD00^FS
^FO60,180
^BCN,47,Y,N,N
^FD210000983917^FS
^XZ

(Note: The mm and cm positions were converted to dots. Ex: 10mm * 8 dots/mm = 80 dots.)

Future Roadmap

• [x] Add Barcode support (Code 128, EAN-13).
• [x] Add support for Lines and Boxes.
• [ ] Add QR Code support.
• [ ] Add support for Images (Graphics).