zplCore Designer
the embeddable label editor.

01Overview

The designer consists of two parts that always run together: the editor UI (static files, an Angular app without external requests) and a stateless render API in .NET that renders previews, measures the printed geometry of each element for the canvas and converts images and SVGs. Both are delivered by one ASP.NET Core library; the container is that library with a minimal host.

What is in it

• Canvas with all element types: text, barcode (1D/2D, GS1, artistic codes), rectangle, line, circle/ellipse, image, printer-memory graphic, SVG icon, ZPL element, table, RFID.
• Property panel, element list, groups, several pages, grid, rulers, snapping, zoom, undo/redo, clipboard, keyboard shortcuts.
• Data binding with JSON records (from your app or edited in the editor), preview per record, hiding per record, expressions and number formats.
• Previews: ZPL, PDF, PNG, SVG; ZPL analyser and linter; GS1 assistant, RFID fields, image → ZPL, SVG → ZPL, icon library.
• 10 UI languages (en, de, zh, ja, es, fr, pt, it, ar, hi), light and dark, mm / inch / dots, 203 / 300 / 600 dpi.

What is deliberately not in it

• Printing of any kind – your application sends the ZPL (for example with the zplCore SDK).
• Storage, accounts, versions or teams – your application receives the JSON and stores it.
• Data-source connectors – data comes as JSON records from your application.
• An AI copilot and the old zplCloud design format { label, fields } (convert it first).

02Quick start: NuGet (ASP.NET Core)

dotnet add package ZplCore.Designer

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication(/* your scheme */);
builder.Services.AddAuthorization();
builder.Services.AddZplCoreDesigner(o =>
{
    o.Fonts.AddDirectory("fonts");                  // optional: your TTF/OTF printer fonts (E:NAME.TTF)
    o.PrinterGraphics.AddDirectory("graphics");     // optional: your printer-memory graphics (E:NAME.GRF)
    o.Limits.MaxRecordsPerRequest = 500;
});

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapZplCoreDesigner("/designer")
   .RequireAuthorization("label-editors");          // your auth – the designer brings none of its own
app.Run();

The editor is now at /designer/, the API at /designer/api/…, the OpenAPI document at /designer/api/openapi/zplcore-designer.json and a health answer at /designer/healthz. MapZplCoreDesigner returns a convention builder: .RequireAuthorization(…) protects UI and API, .Api and .Ui address one part each (for example a public UI with a protected API).

03Quick start: Docker

docker run -d -p 8080:8080 --read-only --tmpfs /tmp \
  -e ZPLCORE_DESIGNER__AUTH__MODE=apikey \
  -e ZPLCORE_DESIGNER__AUTH__APIKEYS__0=<a key of at least 16 characters> \
  -e ZPLCORE_DESIGNER__ALLOWEDORIGINS__0=https://app.example.com \
  -v ./fonts:/fonts:ro -v ./graphics:/graphics:ro \
  zplcore/designer

The editor is at http://localhost:8080/designer/. The image is distroless (Azure Linux), runs as the non-root user app on port 8080 and works with a read-only root file system and a writable /tmp; it is built for linux/amd64 and linux/arm64. The container is configured with the section Designer as environment variables ZPLCORE_DESIGNER__… (double underscore = nesting, __0 = first list entry); every option of section 09 can be set this way, for example ZPLCORE_DESIGNER__LIMITS__MAXRECORDSPERREQUEST=200.

Mounted folders (all optional, read-only is enough): /fonts printer-memory fonts, /graphics printer-memory graphics, /templates design templates (*.json), /icons your SVG icons, /svg-fonts SVG fonts and glyph sets, /graphic-fonts fonts released for graphic text (ZPLCORE_DESIGNER__FOLDERS__* for other paths). Liveness /healthz, readiness /readyz (renders a tiny label). The API needs the key or token; the static UI and {prefix}/healthz stay public.

Kubernetes: the Helm chart deploy/helm/zplcore-designer (API keys only from an existing secret, non-root, read-only root file system, probes, optional HPA and network policy):

kubectl create secret generic designer-api-keys --from-literal=key1=<key>
helm install designer deploy/helm/zplcore-designer \
  --set auth.apiKey.existingSecret=designer-api-keys \
  --set designer.allowedOrigins[0]=https://app.example.com

04Embedding with JavaScript (iframe)

Every designer host delivers the SDK at {baseUrl}/sdk/zplcore-designer.js (no dependencies, no CDN); with a bundler use the npm package @zplcore/designer. The SDK creates an iframe on the editor and talks to it with postMessage; the iframe isolates styles and scripts completely from your page.

<div id="editor" style="height: 720px"></div>
<script src="https://labels.example.com/designer/sdk/zplcore-designer.js"></script>   <!-- global ZplCoreDesigner -->
<script type="module">
  const editor = await ZplCoreDesigner.mount('#editor', {
    baseUrl: 'https://labels.example.com/designer/',
    design,                                   // design document { label, editor, records } or only the label JSON
    data: [{ name: 'Anna', ean: '9506000134352' }],
    locale: 'en', theme: 'auto', unit: 'mm',
    requestHeaders: { 'X-Api-Key': key },     // container with API key; travels by postMessage, never in a URL
    onChange: (doc) => save(doc)              // user edits only, debounced, incl. records
  });
  const zpl = await editor.getZpl();          // the same ZPL the server prints
</script>

// with a bundler
import { mount } from '@zplcore/designer';
const editor = await mount('#editor', { baseUrl: '/designer/' });

When the editor runs on another origin than your app, list your origin in AllowedOrigins of the designer host; across origins load the classic script (the ES module from another origin would need CORS). Ready-made wrappers for React 19, Vue 3 and Angular are in the SDK's examples/. All options, methods and events: section 11.

05Embedding as a Web Component

<script src="/designer/sdk/zplcore-designer.js"></script>   <!-- defines <zplcore-designer> -->
<zplcore-designer base-url="/designer/" locale="en" theme="auto" unit="mm"
                  features="-gs1,-rfid" style="display: block; height: 720px"></zplcore-designer>
<script type="module">
  const el = document.querySelector('zplcore-designer');
  el.design = doc;                  // or the attribute design='{"label":…}'
  el.data = rows;
  el.addEventListener('zplcore-change', (e) => save(e.detail.design));
  const zpl = await el.getZpl();
</script>

With a bundler: import '@zplcore/designer/element'. The element is a slim wrapper around the iframe SDK (Shadow DOM, the iframe is the part frame): attributes base-url, design, locale, theme, unit, tab, features, read-only, autosave, allowed-origins, timeout, title; properties design, data, requestHeaders; events (bubbling, composed) zplcore-ready, zplcore-change, zplcore-selection-change, zplcore-validation, zplcore-error; all SDK methods on the element. It works in every framework that renders custom elements.

06Blazor

dotnet add package ZplCore.Designer.Blazor

<ZplCoreDesigner @ref="editor" @bind-Design="design" Data="rows" BaseUrl="/designer"
                 Locale="en" Theme="DesignerTheme.Auto" ReadOnly="false" Height="720px"
                 OnChange="OnChange" OnSelectionChange="OnSelection" />

@code {
    ZplCoreDesigner? editor;
    JsonObject? design;                  // DesignDocument { schemaVersion, label, editor, records }
    List<object> rows = [new Dictionary<string, object?> { ["name"] = "Anna", ["ean"] = "9506000134352" }];

    async Task Export()
    {
        string zpl = await editor!.GetZplAsync();
        byte[] pdf = await editor.GetPdfAsync();
    }
}

// same host (Blazor Server or a hosted WebAssembly app)
builder.Services.AddZplCoreDesigner();
app.MapZplCoreDesigner("/designer").RequireAuthorization();   // your auth

The component wraps the JavaScript SDK for Blazor Server and WebAssembly (interactive render modes; nothing happens during prerendering). The editor is served by a ZplCore.Designer host in the same app or by the container: BaseUrl="https://labels.example.com/designer", list your app in ZPLCORE_DESIGNER__ALLOWEDORIGINS__0 and pass the key with RequestHeaders. Designs, ZPL and PDFs come back as byte streams, so the SignalR message limit of Blazor Server does not apply.

Methods: GetDesignAsync, SetDesignAsync, SetDataAsync, GetZplAsync, GetPdfAsync, GetPngAsync, GetSelectionAsync, ValidateAsync, UndoAsync, RedoAsync, SetLocaleAsync, SetThemeAsync, SetRequestHeadersAsync.

07WPF / WinForms with WebView2

A desktop app starts the designer in its own process (NuGet ZplCore.Designer, Kestrel on a random 127.0.0.1 port) and shows it in WebView2. A small bridge page mounts the editor with the JavaScript SDK and forwards commands and events between C# (CoreWebView2.PostWebMessageAsString / WebMessageReceived) and the editor. The API answers only requests with a random per-process token, so other programs on the machine cannot use the port; nothing leaves the machine.

// samples/DesignerWpf: host on a random loopback port, API only with a per-process token
var host = await LocalDesignerHost.StartAsync(Path.Combine(AppContext.BaseDirectory, "bridge"));
await Web.EnsureCoreWebView2Async();
var core = Web.CoreWebView2;
var bridge = new DesignerBridge(json => { core.PostWebMessageAsString(json); return Task.CompletedTask; });
core.WebMessageReceived += (_, e) => bridge.OnMessage(e.TryGetWebMessageAsString());
core.Navigate(host.BridgePageUrl);                 // the bridge page mounts the editor with the JS SDK
await bridge.InitAsync(host.DesignerUrl, design, data, "en", headers: host.Headers);

string zpl = await bridge.GetZplAsync();
JsonObject? doc = await bridge.GetDesignAsync();

The sample samples/DesignerWpf (shared parts in samples/designer-embed: bridge page, DesignerBridge, LocalDesignerHost, record import from JSON or CSV) opens and saves designs, loads records, exports ZPL and PDF and switches undo/redo and the language. It needs the WebView2 runtime.

08.NET MAUI

A HybridWebView shows the same bridge page; commands and events go through DesignerBridge. On Windows the designer host runs inside the app (LocalDesignerHost); on Android, iOS and Mac Catalyst the app uses a designer host or the container on your network – allow the page origin there:

ZPLCORE_DESIGNER__ALLOWEDORIGINS__0=https://0.0.0.1   # Android
ZPLCORE_DESIGNER__ALLOWEDORIGINS__1=app://0.0.0.1     # iOS / Mac Catalyst

The sample samples/DesignerMaui needs the MAUI workloads (dotnet workload install maui-windows maui-android) and is not part of the solution. The canvas is designed for mouse and pen; on touch devices the editor works with limitations.

09Options and configuration

AddZplCoreDesigner(o => …) configures ZplCoreDesignerOptions; the container binds the same object from the section Designer.

Limits

Extension points

Interfaces you register in DI or pass in the options: IFontProvider, IPrinterGraphicsProvider, IIconProvider, ITemplateProvider (content), IDesignerAuthorization (allow or refuse an operation per request), IRenderObserver (logging, metrics) and IDesignerLicenseValidator (licence check).

Configuration of the editor UI

The UI reads, later sources winning: {prefix}/config.json of the server (features, embedding origins, branding – no secrets) → window.__ZPLCORE_DESIGNER__ of a host page → the query string for display options only (locale, theme, unit, tab, autosave=0, features=-images,-fonts). The API base, request headers and origins never come from the URL. autosave (default on) keeps a draft in the browser's local storage under the prefix zplcore.designer.; switch it off when your app stores the design.

10Render API reference

All routes are relative to {prefix}/api (e.g. /designer/api). Requests and responses are UTF-8 JSON with camelCase names; every request is self-contained, nothing is stored. Responses carry X-ZplCore-Designer-Api: 1. The editor uses this API; your backend can call it directly (with the host's authentication or the container's API key).

Design rendering

{
  "document": { "label": { "unit": "Mm", "width": 60, "height": 40, "items": [
    { "type": "text", "name": "name", "x": 3, "y": 3, "dataField": "name", "fontSize": 14 } ] } },
  "records": [ { "name": "Anna" }, { "name": "Ben" } ]
}

document is a design document (or { "label": … }); the label is read strictly (unknown properties → 400). Values come from records/record, not from document.records. Every image is the rendered /zpl result: preview = print.

curl -X POST https://labels.example.com/designer/api/zpl \
  -H "X-Api-Key: $DESIGNER_API_KEY" -H "Content-Type: application/json" \
  -d @request.json

Canvas helpers

Conversion and analysis

Errors

{ "error": "The request body is larger than 16,777,216 bytes.", "code": "too_large" }

Server options for the UI: GET {prefix}/config.json; health: GET {prefix}/healthz → { status, version, buildTimeUtc }. The complete OpenAPI description is served at {prefix}/api/openapi/zplcore-designer.json by your own host.

11JavaScript API

ZplCoreDesigner.mount(target, options)

Creates the editor in target (element or selector) and resolves with an editor object once the editor answers.

Methods (all return promises)

All methods return promises; failures reject with ZplCoreDesignerError (code: timeout, command_failed, ready_timeout, destroyed, invalid_options …). createDesigner() returns the instance at once (commands wait until it is ready).

The postMessage protocol

Without the SDK you can talk to the iframe directly (protocol version 2). Host → editor: { source: 'zplcore-host', type, id, payload }; editor → host: { source: 'zplcore', type: 'result', id, payload } and the events ready and change (debounced, { design, records }). Commands: ping, getDesign, setDesign { design, records? }, setData { records }, getZpl { records? }, getPdf, getPng { record? } (both { mimeType, base64 }), undo, redo, setLocale { locale }, setTheme { theme }. The first valid sender fixes the host origin (or the allow-list AllowedOrigins); answers go only to that origin, never to *. The SDK additionally uses a start handshake (?embed=sdk: the editor sends hello, the SDK answers init with headers, read-only mode, design and records before the first API call) and the commands setReadOnly, setRequestHeaders, getSelection, setValidation, validate with the events selectionChange, validation and error. The live editor on this site uses exactly this protocol.

12Design document schema

A design is a JSON document with five parts. Only label is required; the editor writes only values that differ from their default.

{
  "schemaVersion": 4,
  "label":   { "unit": "Mm", "width": 100, "height": 50, "items": [ … ] },
  "editor":  { "version": 1, "dpi": 203, "items": { "ean": { "locked": true } }, "groups": [] },
  "records": [ { "name": "Anna", "metadata": { "promo": { "isRendered": false } } } ],
  "uiSettings": { "zoom": 120, "tab": "pdf" }
}

The editor part

Compatibility promise

• Within a schema version only additive changes: new optional properties whose default keeps the previous print and behaviour.
• Renaming, removing, a new type, meaning or default ⇒ a new version (label.schemaVersion or editor.version) with a migration step; every version reads all older ones.
• Unknown properties in editor are kept and written back, so an older host never damages a newer design. At API boundaries the label is read strictly.

13Security and operations

• No user management of its own. NuGet: your authentication and policies. Container: apikey, jwt (OIDC) or explicitly none.
• Embedding: frame-ancestors and CORS from AllowedOrigins; postMessage answers only to the fixed host origin.
• Inputs: size limits per request, render slots with queue and time limit, optional rate limit per IP; SVGs are sanitised (no scripts, no external references), the server never fetches URLs, ZPL elements are only rendered.
• No storage, no telemetry: the server keeps nothing between requests (only caches of measured geometry); no phone-home, no CDN – the UI loads every file from your host.
• Scaling: stateless, so any number of instances without sticky sessions. Native dependencies (SkiaSharp, HarfBuzz, PDFium, ZXing) support Linux x64/arm64 (glibc), Windows and macOS.
• Monitoring: health {prefix}/healthz (container also /healthz, /readyz), metrics meter ZplCore.Designer (zplcore.designer.requests, zplcore.designer.duration, zplcore.designer.records), OpenTelemetry export (OTEL_EXPORTER_OTLP_ENDPOINT) and structured JSON logs in the container.
• Container: distroless base (Azure Linux), non-root user app, read-only root file system with a writable /tmp; Helm chart with dropped capabilities, seccomp and optional network policy.
• Privacy: designs and records stay in your application; the editor's draft lives only in the user's browser and can be switched off (autosave=0).

14Licensing

The zplCore Designer is part of the commercial zplCore.com product family. Licence model and prices are not published yet; contact us for a trial version or an offer. The live editor on this site is free to try with demo limits.