How to Center QR Codes on Zebra Labels using ZPL Code

Introduction

If you’ve ever needed to print dynamically generated labels using a Zebra printer, you probably know how challenging it can be to precisely position visual elements such as QR codes.

This is especially true if the printer’s native design IDE doesn’t allow dynamically defining QR codes or other types of barcodes. In Dymo printers, for example, these properties can be defined at design time, and the automatically generated code is already prepared to handle different data lengths and scenarios seamlessly.

This article explains a practical and reliable way to center QR codes horizontally (along the X-axis) in ZPL (Zebra Programming Language), ensuring that your labels always look clean and consistent, regardless of the length of the encoded data.

By the end of this guide, you’ll understand:

• The essential ZPL commands used to create a QR code.
• How to calculate the correct positioning dynamically.
• How to integrate this logic into an OutSystems reactive web app using the Zebra Browser Print SDK.

Contextualization

Zebra printers use their native language, ZPL, to build labels by defining text, barcodes, and layout through a sequence of commands.

While ZPL might look complex at first, you don’t need to be an expert to use it effectively. With a basic understanding of a few commands and some math, you can achieve professional-level results.

For reference, Zebra provides the official ZPL Programming Guide, which is an invaluable resource if you want to dive deeper into syntax and parameters.

Labelary Online ZPL Viewer — Preview of a label generated from ZPL code.

ZPL Commands that Build a QR Code

Here’s a simple ZPL template for a QR code:

^XA
^FOx,y
^BQorientation,model,magnification,errorCorrection
^FDLA,data string^FS
^XZ

Commands’ explanation:

• ^XA / ^XZ — These commands are mandatory, as they define the start and the end of the label, respectively.
• ^FOx,y — Field Origin. As the name suggests, and according to the documentation, it defines the top-left corner as the origin of the field. In other words, when defining ^FOx,y, we are specifying that the QR code will be drawn downward and to the right from the coordinates defined by the x and y values.
• ^BQ — Defines the current field as a QR code and includes a set of parameters that must be configured to ensure the QR code is printed correctly:
• orientation: The rotation of the barcode. This parameter is available only for backward compatibility and can only be set to N (no rotation). - model: The QR code model to use. Valid values are 1 (original) and 2 (enhanced). The default and recommended value is 2 (enhanced).
• magnification: The scale or enlargement factor of the barcode. Any number between 1 and 100 can be used. The default depends on the printer’s density. -errorCorrection: Level of error correction to apply. Options: L, M, Q, or H (increasing reliability)
• ^FD — Field Data. Defines the data to be encoded.
• ^FS — Field Separator. Marks the end of the field.

With these basic commands and a few lines of code, we can print a QR code. However, the real challenge is centering it dynamically, especially if your data varies in length (for example, tracking numbers of different sizes).

How to Calculate and Test the X Position of the Field Origin

Step 1: Understanding What Affects QR Code Size

The size of a QR code depends primarily on two factors:

1. The amount of data it contains (number of characters).
2. The error correction level used.

Image source: QRcode.com

To determine how many modules (squares per side) your QR code will have, refer to the QR Code Capacity Table (Alphanumeric Mode), which relates data length and error correction level.

The required analysis that needs to be done is as follows: given a tracking number with 30 characters (e.g., TRACKING-NUMBER-0001–0002–0003), we need to search the table for the first record where this value fits. In this case, the corresponding value would be 38, so we’ll need 25 modules per side with an error correction level = M.

Step 2: Converting Label Dimensions and QR Code Size to Dots

Zebra printers use dots (pixels) as their unit of measurement. To calculate positioning, we first convert our label’s dimensions to dots.

As an example, we’ll use the following parameters and printer settings:

• Standard shipping label size = 2x4 inches → 50.8x101.6 mm
• Printer density = 8 dots per mm (203 dpi)
• Magnification factor = 8 (same as printer density)

Calculations:

1. LabelWidthInDots = Label Width x Printer Density = 50.8 mm × 8 dpmm = 406 dots (rounded value).
2. QRCodeSizeInDots = Modules per Side x Magnification Factor = 25 x 8 = 200 dots.

Step 3: Calculating the Centered X-Position

To center the QR code horizontally, we use a simple formula:

X = (LabelWidthInDots — QRCodeSizeInDots) / 2 = (406–200) / 2 = 103

In this case, the Y value can be manually adjusted, as it only depends on the vertical layout of the elements on the label. If the design includes additional components such as text, logos, or other barcodes, this value should be set accordingly to maintain proper spacing between them. However, changes to the Y coordinate do not affect the horizontal alignment of the QR code, so it remains a static parameter in the label design, independent of the QR code’s size or content.

The X value, on the other hand, is where the real challenge lies. Because the size of a QR code varies with the amount of encoded data, the origin point (X) must be calculated dynamically. In some cases, a smaller QR code requires a larger X value, while a larger QR code requires a smaller one. This dynamic approach compensates for these size variations automatically, ensuring that the QR code always stays centered on the label, regardless of the data length.

In the end, our ZPL code will look something like this:

^XA
^FO103,300
^BQN,2,8,M
^FH\^FDLA,TRACKING-NUMBER-0001-0002-0003^FS
^XZ

Step 4: Testing the Output

For quick validation, you can use Labelary’s ZPL Viewer, which is an excellent online tool to preview and debug your ZPL code before printing.

Step 5: Integrating with your OutSystems App

To implement this logic in your OutSystems application, you can use the “Zebra — Browser Print SDK” available in the OutSystems Forge.

This component allows your web app to:

• Detect available Zebra printers.
• Fetch the default device.
• Send ZPL commands directly to the printer.

Once your ZPL code is built dynamically in your client action, call the “SendDataToPrinter” action, passing:

• The printer’s ID.
• The calculated ZPL code.

This approach enables printing perfectly centered QR codes directly from your OutSystems app (no manual adjustments required).

Final Thoughts

Centering QR codes on Zebra labels may seem like a minor visual adjustment, but in practice, it significantly improves readability, consistency, and professional appearance.

By understanding how ZPL calculates positions and by implementing dynamic positioning, you can ensure your printed labels always look precise, regardless of the content length.

The same approach can be adapted to other label elements, such as barcodes, images, or text fields, ensuring your label generation process remains robust, dynamic, and printer-agnostic.

Thanks for reading!