ZPLRenderer

ZPL Renderer is a desktop application that interprets ZPL (Zebra Programming Language) commands and renders them as a visual preview of what a label will look like when printed on a physical Zebra printer. It is a companion tool to Commander4j, LabelServer4j, and AutoLab4j.

Purpose

ZPL is a text-based command language used to define label layouts, text, graphics, and barcodes for Zebra label printers. The commands are sent directly to the printer as a stream of characters and are not human-readable. ZPL Renderer allows you to:

• Load a ZPL file and see what the label will look like before sending it to a printer
• Listen on a network socket so that any application sending ZPL to that port renders the label on screen in real time
• Zoom in and out to examine label detail
• Preview multiple labels from a single ZPL stream
• Export the rendered label to PDF
• Print the rendered label directly from the application

Running ZPL Renderer

Native install packages for Windows, macOS, and Linux are available from the Downloads page and are the preferred installation method.

Alternatively, ZPL Renderer can be run directly from the distribution archive. It is a Java 25 desktop (Swing) application:

java -jar zplrenderer.jar

On first launch it reads its configuration from xml/config/config.xml.

Loading a ZPL File

Use the Open toolbar button to load a .zpl text file from disk. The label is rendered immediately. Use Refresh to reload the file after editing it externally.

Several example ZPL files are included in the examples/ directory:

File	Contents
example1.zpl	Shipping label with QR code, text, and graphics
example2.zpl	Complex layout with boxes, barcodes, and logo
barcodes.zpl	Showcase of all supported barcode types
pallet_labels.zpl	Pallet label examples typical of Commander4j output
fonts.zpl	Font size and style demonstration
shipping.zpl	Shipping label sample
character.zpl	Character set reference
grid.zpl	Layout grid for alignment reference

Network Socket Mode

ZPL Renderer can listen on a TCP/IP port and render any ZPL label stream sent to it. This allows Commander4j, LabelServer4j, or any other application to use ZPL Renderer as a virtual printer — sending ZPL to the socket and seeing the result on screen instead of printing to paper.

The default port is 9100 (the standard Zebra raw print port). The IP address and port are configured in config.xml. Enable listening using the Network button in the toolbar.

ZPL Renderer extracts complete label blocks from the stream, identified by the standard ^XA (start of label) and ^XZ (end of label) delimiters.

REST API

ZPL Renderer can also expose its rendering engine as a lightweight HTTP service. When REST mode is enabled, any application — including a web browser — can submit ZPL to ZPL Renderer over HTTP and receive back a rendered PNG, a multi-page ZIP of PNGs, or a multi-page PDF.

ZPL Renderer must be installed locally and the REST server must be toggled on for any of the URLs in this section to work.

Enabling REST Mode

REST mode is controlled from the toolbar. Alongside the network socket controls, the toolbar provides:

• a REST toggle button (disconnected icon when off, connected icon when on)
• a Port field (default 8080)

Click the REST button to start the server on the chosen port. Click again to stop it. While the server is running, the port field is locked.

A running REST server accepts requests on:

• http://<host>:<port>/ — a small HTML form for pasting ZPL by hand
• http://<host>:<port>/render — the rendering endpoint

Endpoints

Method	URL	Body / Parameters
GET	/render?zpl=...	URL-encoded ZPL in the zpl query parameter (suitable for short payloads or clickable links)
POST	/render	Raw ZPL request body (any Content-Type other than form-encoded), read as ISO-8859-1
POST	/render	application/x-www-form-urlencoded body with a zpl field
GET	/	Returns a built-in HTML form for ad-hoc rendering in a browser

Query Parameters

All parameters are optional. Where a parameter is omitted, the value falls back to the GUI's current settings.

Name	Description	Default
dpi	Printer DPI (e.g. 203, 300, 600)	GUI setting
width	Label width	GUI setting
height	Label height	GUI setting
uom	Unit of measure: cm or inch	GUI setting
mag	Output magnification (1.0 = full DPI)	1.0
page	1-indexed page selector (only used when format=png)	1
format	Output format: png, zip or pdf	png

Output Formats

Format	Content-Type	Description
png	image/png	A single rendered label (the page selected by page). Returns 404 if the page is out of range.
zip	application/zip	All rendered labels packaged as page_1.png, page_2.png, ...
pdf	application/pdf	All rendered labels in a single PDF (raster, one image per page).

Every successful response includes an X-Total-Pages header reporting the number of labels found in the submitted ZPL.

The server also adds permissive CORS headers (Access-Control-Allow-Origin: *) so a web page served from anywhere can call the endpoint via JavaScript. OPTIONS preflight requests are handled.

Example

The link below renders the contents of examples/barcodes.zpl directly in a browser tab using the GET endpoint, with the ZPL inlined as a URL-encoded zpl query parameter:

• Render barcodes.zpl in your browser

To render the same file by uploading it as a POST body (more practical for large payloads), use any HTTP client. With curl:

curl --data-binary @examples/barcodes.zpl \
     "http://127.0.0.1:8080/render?format=pdf" \
     -o barcodes.pdf

For ad-hoc rendering without crafting a URL by hand, open the built-in form:

• http://127.0.0.1:8080/

Zoom

Use the zoom controls in the toolbar to scale the rendered label between 0.10× and 2.00×. The default zoom is configured in config.xml (default: 0.5×). This is useful for examining barcode detail or checking overall label proportions.

Multiple Labels

When a ZPL file or network stream contains multiple labels, ZPL Renderer displays them as pages. Navigation controls allow stepping through each label. The maximum number of pages displayed is configurable (default: 3).

Export and Print

• PDF Export — saves the rendered label as a vector PDF using Apache PDFBox
• Print — sends the rendered label to a system printer

Supported ZPL Commands

ZPL Renderer supports over 100 ZPL commands. Key categories:

Label Setup

Command	Description
^XA	Start of label
^XZ	End of label
^LL	Label length
^LH	Label home (origin offset)
^LT	Label top offset
^PQ	Print quantity
^CD	Change delimiter character
^CC	Change caret character

Text and Fields

Command	Description
^FO	Field origin (X,Y position from top-left)
^FT	Field typeset (X,Y position from bottom-left)
^FD	Field data (the text content)
^FS	Field separator
^FR	Field reverse (inverted colours)
^FW	Field orientation/rotation
^FX	Comment (ignored in output)

Fonts

Command	Description
^A0–^AZ	Select font by ID
^CF	Change default alphanumeric font
^CI	Change international character set/encoding

Graphics

Command	Description
^GB	Graphic box (rectangle)
^GC	Graphic circle
^GD	Graphic diagonal line
^GE	Graphic ellipse
^GF	Graphic field (embedded image data)
^GS	Graphic symbol

Barcodes

Command	Description
^BC	Code 128 / GS1-128 (EAN-128)
^BE	EAN-13
^B8	EAN-8
^B3	Code 39
^B2	Interleaved 2 of 5
^B1	Code 11
^BQ	QR Code
^B7	PDF417
^B0 / ^BO	Aztec
^BY	Bar code field defaults (width, ratio, height)

Barcode rendering uses the OkapiBarcode library. GS1 application identifiers are interpreted from xml/config/gs1_app_defs.xml.

Configuration

config.xml

Located at xml/config/config.xml:

Setting	Description
Input folder	Default directory for ZPL file loading (default: ./examples)
Port	Network socket port to listen on (default: 9100)
Default magnification	Starting zoom level (default: 0.5)
Max pages	Maximum number of label pages to display (default: 3)

fonts.xml

Located at xml/config/fonts.xml, this file maps ZPL font IDs (0, A–Z) to TrueType font files and defines their pixel dimensions. This allows ZPL Renderer to simulate the fonts installed in a physical Zebra printer.

Included fonts: Bitstream Vera, Anonymous Pro, ATTriumvirate.

If your labels use fonts that differ from the defaults, edit fonts.xml to match the font metrics of your target printer.

Relationship to Commander4j

Commander4j generates ZPL label streams for pallet and case labels. ZPL Renderer allows you to preview these labels before deploying them to production printers, and to verify that label templates produce the correct output after making changes to the template syntax. See Label Template Syntax and Zebra ZPL Label for information on ZPL label authoring within Commander4j.

See also: Zebra ZPL Label, Label Template Syntax, Printer Queues, Production Lines & Labellers