DEV Community: Azeem Ullah

Printing shipping and product labels from a web app (ZPL and TSPL, no PDF)

Azeem Ullah — Fri, 09 Oct 2026 09:41:36 +0000

If your web app ships parcels, prices products or tracks stock, sooner or later someone asks: "Can it print the label straight to the Zebra?"

The usual first attempt is to generate a PDF and call window.print(). That works badly. The label comes out scaled, shifted or split across two labels, and every PC needs its own driver settings. Label printers have their own languages, and sending those directly is simpler and much more reliable.

This post covers the two languages you'll meet most (ZPL and TSPL), the units and sizes that trip people up, and how to get the bytes from a browser to the printer.

Two languages cover most printers

Language	Printers
ZPL	Zebra, and most printers sold as "Zebra-compatible"
TSPL	TSC, 4BARCODE, many Xprinter and generic 4" label printers
EPL	older Zebra/Eltron models (avoid for new work)

Both are plain text. You build a string, send it to the printer as-is (raw), and the printer draws the label itself. No driver rendering, no PDF, no scaling.

Units: everything is in dots

This is where most first labels go wrong. Coordinates are in printer dots, not millimetres or pixels:

203 dpi printers (the common ones): 8 dots per mm
300 dpi printers: about 11.8 dots per mm

So a 4 × 6 inch shipping label is 812 × 1218 dots at 203 dpi, and 1200 × 1800 at 300 dpi. If your label prints at two-thirds size, you wrote it for 203 dpi and sent it to a 300 dpi printer (or the other way round). Keep the dpi in your printer settings and multiply.

ZPL: a shipping label

^XA
^PW812
^LL1218
^CI28
^CF0,40
^FO40,40^FDShip to: Jane Doe^FS
^CF0,30
^FO40,90^FD221B Baker Street, London^FS
^FO40,150^BY3^BCN,120,Y,N,N^FD1Z999AA10123456784^FS
^FO40,320^BQN,2,6^FDQA,https://example.com/track/1Z999AA10123456784^FS
^XZ

What the commands do:

^XA … ^XZ: start and end of a label
^PW812 / ^LL1218: print width and label length in dots (4 × 6" at 203 dpi)
^CI28: treat field data as UTF-8, so é, ü and £ work with the built-in scalable font
^CF0,40: default font 0 (scalable), 40 dots high
^FOx,y: field origin (top-left of the next element)
^FD…^FS: field data, then field separator
^BY3^BCN,120,Y,N,N: Code 128 barcode, module width 3, 120 dots high, human-readable text underneath
^BQN,2,6 + ^FDQA,…: QR code, magnification 6. The QA, prefix means error-correction level Q and automatic input mode. It isn't part of your data.

Tip: paste ZPL into the free Labelary viewer to see the label before you print a single one. It saves a lot of paper.

TSPL: a product label

SIZE 50 mm, 30 mm
GAP 2 mm, 0 mm
DIRECTION 1
CLS
TEXT 20,20,"3",0,1,1,"Organic Honey 500g"
TEXT 20,60,"2",0,1,1,"Price: 9.99"
BARCODE 20,100,"128",70,1,0,2,2,"SKU-000123"
PRINT 1,1

SIZE / GAP: label size and the gap between labels. TSPL lets you use mm here, but TEXT and BARCODE positions are still in dots.
CLS: clear the image buffer. Forget it and you'll print the previous label on top of the new one.
TEXT x,y,"font",rotation,x-mul,y-mul,"content"
BARCODE x,y,"128",height,readable,rotation,narrow,wide,"content"
QRCODE x,y,M,4,A,0,"https://…" adds a QR code (ECC level M, cell width 4).
PRINT 1,1: print one copy of one set

End each line with \r\n. Many printers accept \n, but some older firmware doesn't.

Common gotchas

Wrong gap/label length = blank labels or a label skipped every time. Calibrate the media sensor once. On Zebra, hold the feed button or send ~JC. On TSC, use the printer's utility or the AUTODETECT command. Then make sure ^LL / SIZE match the real stock.
Built-in fonts are limited. ZPL's font 0 plus ^CI28 handles most Latin text. TSPL's bitmap fonts are often ASCII-only. For Arabic, Cyrillic or CJK, either install a font on the printer or draw the text as an image in the browser (a <canvas>), then send it with ZPL ^GFA or TSPL BITMAP. Treat the image as 1-bit and threshold it, because label printers don't do greys.
Don't send ZPL through a "normal" print job. On Windows, a job submitted through the driver with datatype RAW (OpenPrinter → StartDocPrinter with "RAW" → WritePrinter) passes your ZPL through untouched. Printing a text file through the driver instead prints the ZPL source code as text on the label. On macOS/Linux, lp -d <printer> -o raw label.zpl does the right thing.
Network label printers listen on TCP port 9100. nc 192.168.1.60 9100 < label.zpl is the fastest way to test one. Browsers can't open raw TCP sockets, though, which brings us to…

Getting the bytes from the browser to the printer

Option 1: the vendor's agent

Zebra ships a free local agent called Browser Print, with a JS library. If every printer you'll ever support is a Zebra, use it. It doesn't help with TSC and the many generic TSPL printers, and you'll need a separate solution for receipt printers.

Option 2: WebUSB

Chromium-only, needs a user gesture to pair, and on Windows the installed driver usually holds the USB interface, so the browser can't claim it. It's fine for a kiosk where you control the machine, and painful anywhere else.

Option 3: your own small local agent

A program on the PC listens on 127.0.0.1, your page POSTs the ZPL/TSPL string to it, and it writes the bytes to the OS print queue as RAW (or to TCP 9100 for network printers). It's about a hundred lines of code, plus the parts people skip:

answer Chrome's Local Network Access preflight with Access-Control-Allow-Private-Network: true. If you pass targetAddressSpace to fetch, use 'loopback' for 127.0.0.1. In Chrome 155, 'local' fails.
bind to 127.0.0.1 only, check the Origin header against an allowlist, and reject non-loopback Host headers (DNS rebinding)
lock per printer so two tabs don't interleave two labels

I wrote up the receipt-printer side of this (ESC/POS, printer widths, raster images) in a previous post.

If you'd rather not build the agent

I packaged that agent as Thermalink: a single ~7 MB binary for Windows/macOS/Linux plus a JS SDK. For label printers it's a pure raw passthrough: you write the ZPL/TSPL, and it gets the bytes to the right printer (USB via the OS queue, or network via 9100). The same agent also does receipt printers, where it renders receipts as images.

const tl = new Thermalink();
await tl.printRaw(zpl, { printer: 'labels' }); // 'labels' = alias for the Zebra/TSC queue or tcp://ip:9100

To be upfront: I've tested it on a real BIXOLON receipt printer, and the raw label path is covered by automated tests, but I haven't tested it on a physical label printer yet. If you try it on one, I'd like to hear how it went. It's a paid one-time download with full source: https://7207381545467.gumroad.com/l/xwyogp. Disclosure: I built it.

Everything above works without it too. If you're stuck on a specific label printer, drop the model and your ZPL/TSPL in the comments and I'll take a look.

Printing receipts silently from a web app: what actually works in 2026

Azeem Ullah — Fri, 09 Oct 2026 08:03:46 +0000

If you've built a POS, restaurant or warehouse web app, you've hit the receipt-printer wall: the browser wants to show a print dialog, the cashier wants the receipt now, and the printer wants raw bytes.

Here's what I learned getting a web page to print to a thermal receipt printer with no dialog, including two gotchas that cost me real time.

Option 1: `window.print()`

Works everywhere, but:

it always shows a dialog (outside kiosk mode)
it adds page margins and scaling you don't control
it can't cut the paper or open the cash drawer

Fine for the occasional print, painful at a busy counter.

Option 2: WebUSB / Web Serial

No install, but it's Chromium-only, needs a user gesture to pair the device, and on Windows it fights the installed printer driver for the USB interface. It's OK for kiosks you fully control.

Option 3: a local agent (what most POS apps end up doing)

A small program on the shop PC listens on 127.0.0.1, and your page calls it with fetch(). It talks to the printer through the OS print queue or a network socket. Three things to get right:

1. Chrome's Local Network Access rules

An https:// site calling http://127.0.0.1 triggers a CORS preflight that must be answered with:

Access-Control-Allow-Private-Network: true

And if you pass the newer targetAddressSpace fetch option, it has to match the real address space. In Chrome 155, targetAddressSpace: 'local' for a loopback address makes the fetch fail outright. 'loopback' (or no option) works:

await fetch('http://127.0.0.1:17777/v1/health', { targetAddressSpace: 'loopback' });

2. Security

Anything listening on localhost can be called by any website the user opens. At minimum:

bind to 127.0.0.1 only, never 0.0.0.0
check the Origin header against an allowlist (browsers set it, and pages can't fake it)
reject requests whose Host header isn't a loopback name, which blocks DNS-rebinding attacks
require an API key for non-browser callers (no Origin header)

3. Printer width is never what the spec sheet says

This one surprised me. "80 mm" printers differ in DPI (180 vs 203), some have a 58 mm mode switch, and they all keep their own margins. My BIXOLON SRP-352plusIII is 576 dots wide on paper (the spec sheet), but in practice only 568 dots print. Text at the very right edge got clipped.

If you build receipts out of fixed 48-character text lines, they'll wrap or clip differently on the next printer you meet. The approach that fixed it for me: render the receipt as a bitmap at the printer's measured width (real TTF fonts, measured columns, QR codes, barcodes) and send it as an ESC/POS raster image. Then it looks the same on every brand.

How to measure: print a ruler image 640 dots wide with a tick every 8 dots and a number every 32 dots, each number ending at its tick. The last fully readable number (+8 per extra tick) is the usable width.

ESC/POS cheat sheet

What	Bytes
Initialize	`1B 40`
Partial cut	`1D 56 01`
Kick cash drawer (pin 2)	`1B 70 00 19 FA`
Raster image	`1D 76 30 00 xL xH yL yH` + 1 bit per dot, MSB first

Tips:

Send raster images in bands of about 128 rows. Cheap printers overflow their buffer on one huge image.
On Windows, send bytes through the spooler with datatype RAW (OpenPrinter → StartDocPrinter with "RAW" → WritePrinter). Then any installed driver works, and it won't re-render your bytes.
On macOS/Linux, lp -d <printer> -o raw does the same through CUPS.
Network printers almost always accept raw bytes on TCP port 9100.

If you'd rather not build it

I packaged all of the above as Thermalink: a ~7 MB agent for Windows/macOS/Linux plus a small JS SDK. It has image mode (and a text mode for slow links), a calibrate command that prints that ruler, QR/barcodes/logos, cash drawer, label printers (ZPL/TSPL), and full source:

const tl = new Thermalink();
await tl.print(
  Thermalink.receipt()
    .title('BLUE DOOR CAFE')
    .row('Flat white x2', '8.00')
    .row('TOTAL', '8.00', { bold: true })
    .qr('https://example.com/r/A1B2C3')
    .cut()
);

It's a paid, one-time download: https://7207381545467.gumroad.com/l/xwyogp. Disclosure: I built it. Everything in this article works without it too. Happy to answer ESC/POS questions in the comments.