Skip to main content

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

zpl
^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,L put 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,40 started the second and third lines at x 81, against 43 for the first.

New lines: \&

zpl
^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
  • _0A under ^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:
    zpl
    ^XA
    ^CF0,40
    ^FO40,40^FB732,2,0,L^FDEchinacea purpurea Magnus, purple coneflower, family Asteraceae, collected 2019 in Ontario^FS
    ^XZ
    Allow more lines than the text can need. With ^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.
  • ^TB cuts instead. It takes a width and a height in dots, and drops what does not fit:
    zpl
    ^XA
    ^CF0,40
    ^FO40,40^TBN,732,100^FDEchinacea purpurea Magnus, purple coneflower, family Asteraceae, collected 2019 in Ontario^FS
    ^XZ
    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 between < 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. ^TB has no alignment of its own: it takes the third value of ^FO (Center or right-align a barcode in ZPL).
  • ^FT grows 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 ^FO for 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.

json
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:

zpl
^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
^XZ

zeepler 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 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.