Home›Guides›Embed a ZPL Label Viewer in Your Own Site
Embed a ZPL Label Viewer in Your Own Site
Published:
If your documentation, support portal or internal tool ever shows ZPL
code, you can show the rendered label next to it with a single
iframe. No JavaScript library, no API key, no server-side code:
The fragment carries a base64-encoded JSON object with the label:
const veri = {z: "^XA^FO50,50^A0N,40^FDHello^FS^XZ",
d: "8", // dpmm: 6, 8, 12 or 24
w: "4", // width in inches
h: "6"}; // height in inches
const hash = btoa(unescape(encodeURIComponent(JSON.stringify(veri))));
iframe.src = "https://labelixa.com/embed/viewer#" + hash;
The easiest way to get a correct value: open the
ZPL viewer, paste your label and use
"copy link" — the part after # is exactly this format.
Why the ZPL travels in the fragment
The part after # is never sent in the URL of a request,
so your label content does not end up in proxy logs, CDN logs or the
Referer header. The embedded page reads it in the browser and renders
through the same API as the main viewer.
Honest limits
The embed uses the anonymous rendering quota, which is fine for
documentation pages and support threads but not sized for high-traffic
product pages — for that, render server-side over the
API with a key and cache the image. The iframe
adapts to the height you give it, and a small "Labelixa" link stays
visible under the label: that link is the price of the free embed.
Credit the viewer on your own page
The iframe document lives on labelixa.com, so the link inside it counts
for nothing on your site. If you want to credit the free viewer where it
actually helps — and help other people find it — add one caption line
under the frame, in your own HTML:
<p class="caption">Label rendered with the
<a href="https://labelixa.com/tools/zpl-preview">Labelixa ZPL viewer</a></p>
It is optional. The embed works without it.
A badge for your README
If your repository ships ZPL files that are linted in CI (the
diagnostics API or npx labelixa validate
exits non-zero on errors), you can say so with a badge:
[](https://labelixa.com/tools/zpl-preview)
The badge is a static SVG — no counter, no tracking, cached for a day.
Use it only when the claim is true for your repository: a badge that says
"validated" next to files nobody validates helps no one.
Let readers try their own ZPL
The viewer above shows one fixed label. If you want readers to paste and
render their ZPL without leaving your page — a tutorial, a
knowledge-base article, a support form — embed the try widget instead:
It is the same minimal surface with a text box and a Render button. You
may pre-fill it with the same fragment format as the viewer
(/embed/try#…): the label appears in the box and is rendered
once on load. Renders count against the anonymous quota of the reader, not
yours; the text never leaves the browser except as the render request.
Frequently asked questions
Do I need an API key to embed the viewer?
No. The embed runs on the anonymous rendering quota — enough for documentation and support pages. High-traffic pages should render server-side over the API with a key and cache the image.
Is the ZPL in the iframe URL sent to your servers?
The label travels after the # (the URL fragment), which browsers never send as part of a request URL — so it stays out of proxy logs, CDN logs and Referer headers. Rendering itself happens through the same API as the main viewer.
How do I get the ZPL badge for my README?
Copy the Markdown line from the badge section: it embeds a static SVG from labelixa.com and links to the viewer. No sign-up, no counter. Use it only if your repository really validates its ZPL files in CI.
Can I remove the Labelixa link under the label?
No — the visible link is the price of the free embed. If you need an unbranded image, render over the API and serve the PNG yourself.
