zpl-canvas

Render ZPL labels to Canvas and PNG in native JavaScript.

zpl-canvas is a prototype renderer for previewing and testing ZPL/ZPL II labels without calling an external rendering service. It parses ZPL into label elements and draws them with the Canvas 2D API. No public API is stable yet.

Online Demo

Try the browser demo:

https://viniciusftasso.github.io/zpl-canvas/

Install

Browser:

npm install zpl-canvas

Node.js:

npm install zpl-canvas @napi-rs/canvas

@napi-rs/canvas is an optional peer dependency, only needed for rendering in Node.js (no built-in Canvas 2D implementation). If it's missing, the renderer throws ZPL_CANVAS_MISSING_NODE_CANVAS with the install command.

Browser Usage

import { renderZplToCanvas } from "zpl-canvas";

const result = await renderZplToCanvas("^XA^FO40,40^A0N,40,40^FDHello^FS^XZ", {
  dpmm: 8,
  labelWidthMm: 101.6,
  labelHeightMm: 152.4,
  labelIndex: 0,
});

document.body.append(result.canvas);

Node Usage

import { renderZplToPngBuffer } from "zpl-canvas";
import fs from "node:fs/promises";

const result = await renderZplToPngBuffer("^XA^FO40,40^A0N,40,40^FDHello^FS^XZ", {
  dpmm: 8,
  labelWidthMm: 101.6,
  labelHeightMm: 152.4,
  labelIndex: 0,
});

await fs.writeFile("label.png", result.buffer);

console.log(result.metadata.label.copies);

Supported Commands

• Label/page: ^XA ^XZ ^PW ^LL ^LH ^LS ^PQ
• Fields: ^FO ^FT ^FS ^FD ^FH ^FR ^FB
• Fonts: ^CF ^A*
• Graphics: ^GB ^GC ^GE ^GD ^GF ~DG ^XG ^IM
• Barcodes: ^BY ^BC ^B3 ^BA ^B2 ^BE ^BU ^B9 ^BK ^BQ ^BX ^B7 ^BO ^BD

Image support covers raw hex ^GF, Zebra ASCII hex repeat compression, and Z64 deflate/base64 payloads. Known no-op/control commands are silently accepted so real-world labels keep rendering.

Compatibility Notes

• The default canvas uses the physical label size (labelWidthMm, labelHeightMm, dpmm). Use useZplCanvas: true to render with ^PW/^LL as the output canvas dimensions instead.
• Multi-label ZPL is not expanded by ^PQ. The render result includes metadata.labels[] with each renderable label's copies value so callers can decide how to print or display repeated labels.
• Zebra bitmap font parity is still incremental; text falls back to a condensed bold system font stack.

Development

npm run test
npm run check
npm run build
npm run demo:build