Skip to main content

ZPL how-to

Label size and origin in ZPL (^PW, ^LL, ^LH)

ZPL measures a label in dots from its top-left corner. ^PW sets the width, ^LL the length and ^LH where 0,0 is. The printer keeps ^LL and ^LH after the label ends, and in Labelary ^PW carried over too.

In plain ZPL

A 4 × 2 inch label on a 203 dpi printer:

zpl
^XA
^PW812
^LL406
^LH0,0
^CF0,50
^FO40,40^FDRack 4, bay 2^FS
^XZ
  • ^PW812: the print width, 812 dots. Anything to the right of it does not print.
  • ^LL406: the label length, 406 dots. On most label stock the printer finds the length itself, as the section on ^LL below explains.
  • ^LH0,0: the label home, the point every ^FO is measured from. 0,0 is the top-left corner.
  • Zebra's reference asks for ^LL and ^LH before the first ^FS, so put all three straight after ^XA.

Inches to dots

Dots = inches × dots per inch, rounded down. A "203 dpi" printhead has 8 dots per mm, which is 203.2 per inch, and a "300 dpi" one has 12, which is 304.8. Zebra's own formula uses those exact figures.

Label (inches)^PW, ^LL at 203 dpi^PW, ^LL at 300 dpi
2 × 1406, 203609, 304
3 × 1609, 203914, 304
3 × 2609, 406914, 609
4 × 2812, 4061219, 609
4 × 3812, 6091219, 914
4 × 6812, 12191219, 1828

^PW: what is past it is cut off

The same line of text with the print width set to 400 dots:

zpl
^XA
^PW400
^LL406
^LH0,0
^CF0,50
^FO40,40^FDRack 4, bay 2, top shelf^FS
^XZ

In Labelary, the text stops at dot 400 in the middle of a word: "Rack 4, bay 2, top" prints and the rest does not. There is no error. A ^PW wider than the stock is cut down to the stock's width, Zebra's reference says, so an oversized value does no harm.

^LL: why the label length does not change

A common question about label size is a label that always prints at the same length whatever ^LL says. Zebra's reference explains it: ^LL has a second parameter that decides which media the length applies to. With N, the default, it applies only to continuous media, a roll with nothing between the labels. With Y it applies to gap and mark media too. An ^LL without the second parameter leaves the printer's current setting as it is.

  • On labels with a gap, a notch or a black mark between them, with the setting at N, the printer measures each label itself and starts the next one at the next gap or mark. ^MNY tells it to look for a gap and ^MNM for a mark. A wrong length there is fixed by calibrating the printer to the stock, from its menu or its feed button as its user guide describes, not by ^LL.
  • On continuous media, set ^MNN, and ^LL is the length of each label.

Labelary draws the label at the size you ask it for, so it cannot show any of this. We have not checked it on a printer.

^LH: move the origin

^LH moves 0,0 for every field after it. On stock with a 100-dot printed header, ^LH0,100 lets the coordinates start below it:

zpl
^XA
^PW812
^LL406
^LH0,100
^CF0,50
^FO40,40^FDRack 4, bay 2^FS
^XZ

The text prints 140 dots down: 100 from ^LH plus 40 from ^FO.

The next label inherits them

The printer keeps ^LH and ^LL until it is switched off or gets new values, Zebra's reference says, and in Labelary ^PW carried over too. A label that sets none of them prints with whatever the previous label, or other software, left behind. Sent after the label above, this one prints its text 140 dots down, not 40:

zpl
^XA
^CF0,50
^FO40,40^FDRack 4, bay 3^FS
^XZ

Start every label with all three, ^LH0,0 included, and it prints the same whatever ran before it.

The same label with zeepler

Send this body to POST https://api.zeepler.com/v1/zeeplify with your API key in the x-api-key header. It is a working request, not an illustration: on every change, our tests run this same file through the API's code and compare the result with the ZPL below.

json
1{
2 "config": {
3 "size": "4x2"
4 },
5 "data": {
6 "location": "Rack 4, bay 2",
7 "code": "R04-B02"
8 },
9 "templates": [
10 {
11 "type": "Text",
12 "dataPath": "location",
13 "coords": [40, 40],
14 "font": "0,50"
15 },
16 {
17 "type": "BarCode",
18 "dataPath": "code",
19 "coords": [40, 120]
20 }
21 ]
22}

And the ZPL that comes back, ready to send to the printer:

zpl
^XA^MCY^XZ
    ^XA
    ^SZ2
    ^MMT
    ^MNY
    ^LL406
    ^PW812
    ^LH0,0
^CF0,50^FO40,40^FDRack 4, bay 2^FS
^BY2,2,59^FO40,120^BCN,,N,N,N,A^FDR04-B02^FS
^XZ

size sets the label size. zeepler starts every label with ^LL, ^PW and ^LH0,0, so a value left behind by an earlier label never moves this one. It also sends ^MNY, labels with a gap between them, unless mediaTracking says otherwise: set it to "M" for labels with a black mark, or "N" for continuous media.

What zeepler does not do yet:

  • size is "3x1" or "4x2", for 203 dpi printers. Any other size is refused with a 400 whose error for config.size is must be one of 3x1, 4x2.
  • There is no origin offset. Measure coords from the corner of the label.
  • An element that starts outside the label is refused, with the size in dots: must fall inside the label, 812 x 406 dots. Only its starting point is checked, so text that starts inside can still run past the edge and be cut off.

Sending it

  • Call the API from your own server or integration engine, not from a web page. An API key in a browser is a key anyone can copy.
  • A successful call answers 200 with the ZPL as plain text. A request the API cannot turn into a label answers 400 with every problem listed by field, and is not billed.
  • Send the ZPL to a Zebra or other ZPL printer at 203 dpi. At 300 dpi the same label prints at two-thirds of the size.

The API reference has every field and status code.

Before you go live

  • Text does not wrap. A value longer than the space you left runs off the edge of the label, so set maxLength on any field whose length you do not control.
  • Coordinates are in dots from the top-left corner. Print one label, measure it, and adjust: there is no preview.
  • Scan every barcode and QR code on a printed label before relying on it.

Related guides

Help with an integration

Email info@zeepler.com. You will get a reply within 2 business days. The support policy covers response times and version changes.