Label

import { Label, inches, mm, dots, Orientation, ZebraFontFamily } from "@zplkit/core";

Label builds one label as a list of ZPL commands. Each drawing method adds a field and returns the label, so calls chain. Method calls introduces it; this page lists every method and option.

new Label(options)Copy Anchor Link

new Label(options: LabelOptions): Label

const label = new Label({ width: inches(4), height: inches(6), dpmm: 8 });

MethodsCopy Anchor Link

DrawingCopy Anchor Link

textCopy Anchor Link

label.text(options: TextOptions): this

Adds text in one of the printer's fonts or a font file on the printer. Characters ZPL would read as commands are escaped.

label.text({
  position: { x: mm(5), y: mm(5) },
  text: "Harbor Parts Co.",
  font: { height: mm(5) },
});

font takes:

Text can run down or right to left, be spaced out, wrap in a block, show the printer's date and time, or count up on each copy:

// 001, 002, 003… on the 500 copies
const label = new Label({ width: inches(4), height: inches(2), dpmm: 8, copies: 500 });
label.text({ position: { x: mm(5), y: mm(5) }, text: "001", serial: {} });

// Printed 28.10.2026, from the printer's clock
label.text({ position: { x: mm(5), y: mm(15) }, text: "Printed %d.%m.%Y", clock: true });

// Wrapped in a block 60 mm wide, centered, on up to 3 lines
label.text({
  position: { x: mm(5), y: mm(25) },
  text: "Keep dry and away from direct sunlight",
  block: { width: mm(60), lines: 3, align: "center" },
});

block takes:

serial takes the following. Barcodes, except QR codes, take it too, to count their data up.

boxCopy Anchor Link

label.box(options: BoxOptions): this

Adds a box, or a line when one side is as thin as the border.

// A 0.5 mm rule across the label
label.box({
  position: { x: mm(5), y: mm(30) },
  width: mm(91),
  height: mm(0.5),
  thickness: mm(0.5),
});

ellipseCopy Anchor Link

label.ellipse(options: EllipseOptions): this

Adds an ellipse, or a solid one when the line is half its width or height.

label.ellipse({
  position: { x: mm(5), y: mm(5) },
  width: mm(30),
  height: mm(15),
  thickness: mm(0.5),
});

circleCopy Anchor Link

label.circle(options: CircleOptions): this

Adds a circle.

graphicCopy Anchor Link

label.graphic(options: GraphicOptions): this

Adds an image converted with ImageConverter.

storedGraphicCopy Anchor Link

label.storedGraphic(options: StoredGraphicOptions): this

Prints an image stored on the printer with PrinterSetup.storeGraphic, without sending it again.

fieldCopy Anchor Link

label.field(options: FieldOptions): this

Adds a field with any command, for elements without their own method. The command is added as written, and the data is escaped.

label.field({
  position: { x: mm(5), y: mm(5) },
  command: "^B8N,100,Y,N",
  data: "1234567",
});

BarcodesCopy Anchor Link

The linear barcodes take these options. The 2D codes take position, data and orientation, plus the options listed with them.

code128Copy Anchor Link

label.code128(options: Code128Options): this

Code 128, the general-purpose barcode for letters, digits and punctuation. Shipping and logistics labels use it most. Writes ^BC.

label.code128({
  position: { x: mm(5), y: mm(5) },
  data: "ORD-10442",
  height: mm(12),
});

Besides the common options:

code39Copy Anchor Link

label.code39(options: Code39Options): this

Code 39: capital letters, digits, space and - . $ / + %. Wider than Code 128 for the same data. Writes ^B3.

label.code39({
  position: { x: mm(5), y: mm(5) },
  data: "PART-77",
  checkDigit: true,
});

Besides the common options:

code93Copy Anchor Link

label.code93(options: Code93Options): this

Code 93, a denser Code 39 with two check characters, which the printer always adds. Writes ^BA.

label.code93({
  position: { x: mm(5), y: mm(5) },
  data: "PART-77",
});

Besides the common options:

code11Copy Anchor Link

label.code11(options: Code11Options): this

Code 11: digits and dashes, used on telecom equipment. Writes ^B1.

label.code11({
  position: { x: mm(5), y: mm(5) },
  data: "123-45",
});

Besides the common options:

codabarCopy Anchor Link

label.codabar(options: CodabarOptions): this

ANSI Codabar: digits and - $ : / . + between a start and a stop letter, A to D. Writes ^BK.

label.codabar({
  position: { x: mm(5), y: mm(5) },
  data: "31117013206375",
  start: "B",
  stop: "D",
});

Besides the common options:

ean13Copy Anchor Link

label.ean13(options: Ean13Options): this

EAN-13 for retail products. Pass 12 digits; the printer adds the check digit. Writes ^BE.

label.ean13({
  position: { x: mm(5), y: mm(5) },
  data: "590123412345",
});

It takes only the options above.

ean8Copy Anchor Link

label.ean8(options: Ean8Options): this

EAN-8 for small retail packages. Pass 7 digits; the printer adds the check digit. Writes ^B8.

label.ean8({
  position: { x: mm(5), y: mm(5) },
  data: "9638507",
});

It takes only the options above.

upcACopy Anchor Link

label.upcA(options: UpcAOptions): this

UPC-A, the 12 digit retail code used in North America. Pass 11 digits; the printer adds the check digit. Writes ^BU.

label.upcA({
  position: { x: mm(5), y: mm(5) },
  data: "03600029145",
});

Besides the common options:

upcECopy Anchor Link

label.upcE(options: UpcEOptions): this

UPC-E, a UPC-A number compressed to 6 digits for small packages. Pass the UPC-A number without its check digit: 10 digits, or 11 starting with the number system. Writes ^B9.

label.upcE({
  position: { x: mm(5), y: mm(5) },
  data: "1230000045",
});

Besides the common options:

upcEanExtensionCopy Anchor Link

label.upcEanExtension(options: UpcEanExtensionOptions): this

The 2 or 5 digit add-on printed to the right of a UPC or EAN code, for example a magazine's issue number. Give it its own position, a little lower and shorter than the main code. Its digits print above the bars by default. Writes ^BS.

label.upcEanExtension({
  position: { x: mm(5), y: mm(5) },
  data: "04414",
});

It takes only the options above.

interleaved2of5Copy Anchor Link

label.interleaved2of5(options: Interleaved2of5Options): this

Interleaved 2 of 5: digits in pairs, common on cartons. The printer adds a leading zero to an odd number of digits. Writes ^B2.

label.interleaved2of5({
  position: { x: mm(5), y: mm(5) },
  data: "10012345678902",
});

Besides the common options:

industrial2of5Copy Anchor Link

label.industrial2of5(options: Industrial2of5Options): this

Industrial 2 of 5: digits, for systems that still read it. Writes ^BI.

label.industrial2of5({
  position: { x: mm(5), y: mm(5) },
  data: "123456",
});

It takes only the options above.

standard2of5Copy Anchor Link

label.standard2of5(options: Standard2of5Options): this

Standard 2 of 5: digits, for systems that still read it. Writes ^BJ.

label.standard2of5({
  position: { x: mm(5), y: mm(5) },
  data: "123456",
});

It takes only the options above.

logmarsCopy Anchor Link

label.logmars(options: LogmarsOptions): this

LOGMARS, Code 39 with a check digit, for U.S. Department of Defense labels. It always prints its text. Writes ^BL.

label.logmars({
  position: { x: mm(5), y: mm(5) },
  data: "12AB",
});

It takes the options above, except printHri.

msiCopy Anchor Link

label.msi(options: MsiOptions): this

MSI: digits, used on shelf labels. One Mod 10 check digit by default. Writes ^BM.

label.msi({
  position: { x: mm(5), y: mm(5) },
  data: "123456",
  checkDigits: "C",
});

Besides the common options:

plesseyCopy Anchor Link

label.plessey(options: PlesseyOptions): this

Plessey: digits and A to F, used on shelf labels. The printer adds an 8 bit check. Writes ^BP.

label.plessey({
  position: { x: mm(5), y: mm(5) },
  data: "12345",
});

Besides the common options:

postnetCopy Anchor Link

label.postnet(options: PostnetOptions): this

USPS POSTNET: a ZIP code of 5, 9 or 11 digits as tall and short bars. The printer adds the check digit, and doesn't print the digits unless printHri is set. Writes ^BZ.

label.postnet({
  position: { x: mm(5), y: mm(5) },
  data: "12345",
  height: dots(40),
});

It takes the linear barcode options above, with printHri off by default.

planetCopy Anchor Link

label.planet(options: PlanetOptions): this

USPS PLANET: 11 or 13 digits as tall and short bars. Writes ^B5.

label.planet({
  position: { x: mm(5), y: mm(5) },
  data: "12345678901",
  height: dots(40),
});

It takes the linear barcode options above, with printHri off by default.

intelligentMailCopy Anchor Link

label.intelligentMail(options: IntelligentMailOptions): this

USPS Intelligent Mail: a 20 digit tracking code followed by a routing code of 0, 5, 9 or 11 digits. Writes ^BZ.

label.intelligentMail({
  position: { x: mm(5), y: mm(5) },
  data: "00123123456123456789",
  height: dots(40),
});

It takes position, data, orientation and height, and never prints its digits.

gs1DataBarCopy Anchor Link

label.gs1DataBar(options: Gs1DataBarOptions): this

GS1 DataBar. The first five types take a GTIN of up to 13 digits; Expanded takes GS1 element strings without parentheses, like 010001234567890517251231. Composite symbols, with a 2D part after a |, aren't drawn by the renderer yet. Writes ^BR.

label.gs1DataBar({
  position: { x: mm(5), y: mm(5) },
  data: "12345678901",
  type: "stacked",
});

Besides the common options:

pdf417Copy Anchor Link

label.pdf417(options: Pdf417Options): this

PDF417, a stacked 2D code for a few hundred characters, used on shipping labels and IDs. Writes ^B7.

label.pdf417({
  position: { x: mm(5), y: mm(5) },
  data: "SHIP 10442 TO AMARA OKAFOR",
  columns: 4,
});

Besides the common options:

microPdf417Copy Anchor Link

label.microPdf417(options: MicroPdf417Options): this

MicroPDF417, a smaller PDF417 for little data. The mode picks its columns, rows and error correction; the ^BF page lists them. Writes ^BF.

label.microPdf417({
  position: { x: mm(5), y: mm(5) },
  data: "ABC123",
  mode: 3,
});

Besides the common options:

qrCodeCopy Anchor Link

label.qrCode(options: QrCodeOptions): this

QR code. The error correction level is added to the data as ZPL requires. Writes ^BQ.

label.qrCode({
  position: { x: mm(5), y: mm(5) },
  data: "https://example.com/orders/10442",
  moduleSize: dots(5),
});

Besides the common options:

dataMatrixCopy Anchor Link

label.dataMatrix(options: DataMatrixOptions): this

Data Matrix, the small square code used to mark parts and medicine. moduleSize is required. Writes ^BX.

label.dataMatrix({
  position: { x: mm(5), y: mm(5) },
  data: "SN-10442",
  moduleSize: dots(4),
});

Besides the common options:

aztecCopy Anchor Link

label.aztec(options: AztecOptions): this

Aztec code, a square code with a bullseye in the middle, used on tickets. Writes ^BO.

label.aztec({
  position: { x: mm(5), y: mm(5) },
  data: "TICKET 10442",
});

Besides the common options:

maxiCodeCopy Anchor Link

label.maxiCode(options: MaxiCodeOptions): this

MaxiCode, the fixed-size code on UPS parcels. In modes 2 and 3 the data starts with the class of service, country code and postal code. Writes ^BD.

label.maxiCode({
  position: { x: mm(5), y: mm(5) },
  data: "001840100014000012345",
  mode: 2,
});

Besides the common options:

SettingsCopy Anchor Link

setDefaultFontCopy Anchor Link

label.setDefaultFont(options: DefaultFontOptions): this

Sets the font (^CF) for text that doesn't set one.

setFieldOrientationCopy Anchor Link

label.setFieldOrientation(orientation: Orientation): this

Sets the orientation (^FW) of the fields that follow and don't give one.

OutputCopy Anchor Link

Lower levelCopy Anchor Link

TypesCopy Anchor Link

Length, Position, Orientation and the other shared types are described in Types.