ZPL how-to
Wrap text and new lines in ZPL
A ZPL field prints on one line, even past the edge of the label. ^FB turns it into a block that wraps at spaces, and \& inside it starts a new line.
Wrap with ^FB
^XA
^CF0,40
^FO40,40^FB732,3,0,L^FDEchinacea purpurea Magnus, purple coneflower, family Asteraceae, collected 2019 in Ontario^FS
^XZ^FB732,3,0,L: a block 732 dots wide, from x 40 to 40 dots short of the right edge of a 4-inch label, up to 3 lines, no extra space between them, left-aligned.- In Labelary it wrapped at spaces into three lines, one under the other, from y 40 to 150. Without
^FB, the same text printed on one line and ran to x 811, the edge of the label. - The third value adds space between lines.
^FB732,3,20,Lput the lines at y 40, 100 and 159, about 60 dots apart instead of 40. - The fifth value indents every line after the first.
^FB732,3,0,L,40started the second and third lines at x 81, against 43 for the first.
New lines: \&
^XA
^CF0,40
^FO40,40^FB732,3,0,L^FDEchinacea purpurea\&Magnus^FS
^XZ\& ends a line, so this printed on two. What did not work in Labelary:
\&without^FB. It is one of^FB's own codes. In a plain field it printed as¢&: in the default character set a backslash prints as ¢.- A line break in the data. Zebra's reference says carriage returns and line feeds in the data are thrown away. The two words joined, as
Echinacea purpureaMagnus:zpl^XA ^CF0,40 ^FO40,40^FB732,3,0,L^FDEchinacea purpurea Magnus^FS ^XZ _0Aunder^FH. In Labelary the field stopped there: only the text before it printed, on one line ending at x 355, where the first line above ends:zpl^XA ^CF0,40 ^FO40,40^FB732,3,0,L^FH^FDEchinacea purpurea_0AMagnus^FS ^XZ
Text printed over itself, or cut off
- More text than lines. Zebra's reference: text beyond the last line overwrites it. With two lines allowed, the third line printed on top of the second:Allow more lines than the text can need. Withzpl
^XA ^CF0,40 ^FO40,40^FB732,2,0,L^FDEchinacea purpurea Magnus, purple coneflower, family Asteraceae, collected 2019 in Ontario^FS ^XZ^FO, unused lines take no space: with five allowed, the same text printed exactly as with three. In Labelary the overprinted label had 17344 dots of ink, against 15652 for its first two lines alone. ^TBcuts instead. It takes a width and a height in dots, and drops what does not fit:This printed two whole lines and dropped the rest, with nothing to show that it had. Zebra's reference says it needs firmware V60.14.x, V50.14.x or later, and reads text betweenzpl^XA ^CF0,40 ^FO40,40^TBN,732,100^FDEchinacea purpurea Magnus, purple coneflower, family Asteraceae, collected 2019 in Ontario^FS ^XZ<and>as an escape sequence. In Labelary its lines were 50 dots apart, not 40, and at a height of 80 the bottom of the second line was cut off at the block's edge. Try the height on a preview.^TBhas no alignment of its own: it takes the third value of^FO(Center or right-align a barcode in ZPL).^FTgrows the block upward. Zebra's reference puts^FT's y at the baseline of the last possible line, so the block is as tall as the lines you allow and grows upward from there. Here the three lines needed more room above y 80 than there was, and the first was cut off at the top of the label. Spare lines move the text up too: at^FT40,200, three lines allowed printed from y 90 to 200, and five from y 10 to 120. Use^FOfor a block, which grows downward.zpl^XA ^CF0,40 ^FT40,80^FB732,3,0,L^FDEchinacea purpurea Magnus, purple coneflower, family Asteraceae, collected 2019 in Ontario^FS ^XZ- Center text in ZPL with ^FB covers centering a block.
Several lines 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.
1{2 "config": {3 "size": "4x2"4 },5 "data": {6 "name": "Echinacea purpurea Magnus",7 "common": "purple coneflower, family Asteraceae",8 "origin": "collected 2019 in Ontario"9 },10 "templates": [11 {12 "type": "Text",13 "dataPath": "name",14 "coords": [40, 40],15 "font": "0,40"16 },17 {18 "type": "Text",19 "dataPath": "common",20 "coords": [40, 80],21 "font": "0,40"22 },23 {24 "type": "Text",25 "dataPath": "origin",26 "coords": [40, 120],27 "font": "0,40"28 }29 ]30}And the ZPL that comes back, ready to send to the printer:
^XA^MCY^XZ
^XA
^SZ2
^MMT
^MNY
^LL406
^PW812
^LH0,0
^CF0,40^FO40,40^FDEchinacea purpurea Magnus^FS
^CF0,40^FO40,80^FDpurple coneflower, family Asteraceae^FS
^CF0,40^FO40,120^FDcollected 2019 in Ontario^FS
^XZzeepler does not wrap text. A Text element prints on one line, and its maxLength cuts a value to that many characters, which is the opposite of wrapping. For text on several lines, give each line its own Text element, one font height apart, and split the text by meaning: here the name, the common name and where it was collected. The three lines printed from y 40 to 150, where the ^FB block above did.
A \& in a value prints as ¢&, as in a plain field above. That holds with align too: zeepler then sends a ^FB, but doubles each backslash in it.
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
200with the ZPL as plain text. A request the API cannot turn into a label answers400with 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
maxLengthon 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
- QR code size in ZPL: How ^BQ magnification sets the size of a QR code, and how to work out the size in dots.
- Printing ^, ~ and _ in ZPL: Why a caret or tilde in your data cuts the field short, and how ^FH prints them.
- Font size in ZPL: Setting text height with ^A and ^CF, converting points to dots, and why ^CF carries over.
- Send ZPL to a Zebra printer from C#: Send ZPL from .NET to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Code 128 barcodes in ZPL: Set a Code 128 barcode's width and height with ^BY and ^BC, work out its width in dots, and pick subsets A, B and C.
- Accented characters in ZPL (^CI28): Print é, ç, ô and € with ^CI28, switch the printer back with ^CI0, and what to do on older firmware.
- Send ZPL to a Zebra printer from Python: Send ZPL from Python to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Change a barcode to a QR code in ZPL: Swap ^BC for ^BQ, start the field data with QA, so the first characters scan, and reset the ^BY left over from the barcode.
- Send ZPL to a Zebra printer from Node.js: Send ZPL from Node.js to a network printer on port 9100 or to a USB printer through a Windows printer share, and print from a web page through your server.
- Label size and origin in ZPL (^PW, ^LL, ^LH): Set the label size in dots with ^PW and ^LL, move 0,0 with ^LH, and stop the last label's settings moving this one.
- Templates in ZPL: store a format with ^DF, fill it with ^XF: Store a label layout on the printer with ^DF and ^FN, fill it with ^XF, and what prints when a field or the format is missing.
- Several labels in one ZPL job: Send several different labels in one job, stop each one inheriting the last one's font and barcode settings, and number a run with ^SN and ^PQ.
- EAN-13 and Code 93 barcodes in ZPL: Print EAN-13 with ^BE and Code 93 with ^BA, and the data each one changes: a replaced check digit, and characters Code 93 cannot hold.
- Print copies of a ZPL label with ^PQ: Print several copies of one label with ^PQ, why ^PQ after ^XZ prints only one, and each serial number twice with ^SN.
- Center text in ZPL with ^FB: Center text of any length with ^FB, why centered text sits a little left, and text too long for the block.
- Center or right-align a barcode in ZPL: Right-align a barcode with the third value of ^FO, center one by working out its width, and why ^FB does not move it.
- Rotate text and barcodes in ZPL: Turn text and barcodes with N, R, I and B, where ^FO and ^FT put a turned field, ^FW and ^POI, and why both stay set.
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.