Skip to content
Taprel
Docs menu API

API

Every call, option and field, for JavaScript, React and Vue.

PrintClient

import { PrintClient } from "@taprel/sdk";

export const printer = new PrintClient({ client: { name: "my-pos" } });

Make one, in a file of its own, and import it wherever you print. Making it connects nothing: the first request does, or connect().

Option Default What it does
client none Your app’s name, as { name: "my-pos" }, sent when connecting. The Taprel app doesn’t show it anywhere yet
reconnect true Reconnects by itself when the app starts or restarts
requestTimeoutMs 150000 How long to wait for a reply. It’s long because the app’s question can wait 2 minutes
url The app’s address on this computer Where to connect

Calls

Call What it does
printDocument(doc, { printer, printerKind, copies }) Prints a receipt or label. Without printer or printerKind, it uses the printer whose type matches the document. copies is 1 to 100
previewDocument(doc, { printer, printerKind }) Draws the document as a base64 PNG, { png }, and prints nothing. See Previews
printPdf(printer, data, { copies, scale, paper }) Prints a PDF through the printer’s driver, see PDFs
printRaw(printer, data) Sends bytes unchanged, in the printer’s own language
listPrinters() The customer’s printers, with the fields under Printers
onStatusChange(listener) Calls listener(status, error) each time the connection changes, see Status. Returns a function that stops listening
connect() Connects now. Gives back { agentVersion, protocol }, or throws a PrintError, like AGENT_NOT_RUNNING
close() Disconnects and stops reconnecting, until the next request or connect()

data is a Uint8Array, ArrayBuffer, Blob, or a string already in base64. Connecting, previews and the printer list never need a plan. When a call can’t do its job, it throws a PrintError, see Errors.

What a print returns

  • jobId: the job’s number in Windows’ print queue. It means Windows has the job, not that paper came out.
  • route: commands, sent in the printer’s own language, or driver, drawn and sent through its Windows driver.
  • warnings: what couldn’t be done, like cutting on a printer that can’t cut. The rest still printed.

Previews

const { png } = await printer.previewDocument(doc);

image.src = `data:image/png;base64,${png}`;

A preview needs the app running, but no printer and no plan. With printer or printerKind, it uses that printer’s paper settings. Without them, a receipt is drawn on an 80 mm roll and a label at its own size. A label’s preview is exactly what prints. A receipt’s is too, except plain English text on ESC/POS, which prints in the printer’s own font.

Status

  • printer.status is the connection now: disconnected, connecting, waiting-for-browser, waiting-for-agent or connected.
  • printer.error is the last connection error, or null.
  • printer.agent is the app’s version, once connected.

onStatusChange only calls its listener when the status changes, not when you start listening, so read printer.status first.

When the app isn’t running, the client tries again by itself: after half a second at first, then less and less often, up to every 10 seconds. It never tries again after ORIGIN_NOT_ALLOWED, and after BROWSER_BLOCKED it waits until the browser’s setting changes.

Printers

Each printer from listPrinters() has:

Field What it is
name The exact name, to pass as printer
kind receipt, label or regular, as set in the Taprel app
mainOfKind true for the one printerKind picks when there are several of that type
status What Windows reports: ready, offline, paused, paperJam, paperOut, doorOpen, noToner or error
jobs Jobs waiting in Windows’ print queue
canPrintSilently false for a printer that always asks where to save, like Microsoft Print to PDF
paperWidthMm A receipt roll’s width, or null
labelWidthMm, labelHeightMm The label size set in the app, or null
language escpos, tspl, zpl or driver
dpi The printer’s resolution
isDefault true for Windows’ default printer
driver, port From Windows
kindGuessed, languageGuessed true when the app guessed it from the name, and nobody has checked it yet

Helpers

Helper What it does
receipt(content) Builds a receipt
label(content, size) Builds a label. size is { width, height } in mm, and optional
browserPermissionTexts The words to show around the browser’s question: beforeQuestion and afterBlock

The client never sends a print twice by itself, so a second click sends a second print. Turn your button off while it prints.

React

@taprel/react needs React 18 or newer. Wrap your app in TaprelProvider, as in the Quick start.

Name What it gives you
TaprelProvider Holds the connection. Takes the client’s options, autoConnect, or your own client as printClient. Its options are read once, when it first appears
usePrint() print, printPdf, printRaw, isPrinting, error, result, warnings, reset
useTaprel() status, error, agent, isConnected, connect, disconnect, client
usePrinters({ kind }) printers, isLoading, error, refresh
usePreview(doc, { printer, printerKind, delayMs }) src, preview, isLoading, error
PrintHelp The customer’s next step. Takes texts, downloadUrl, downloadText, className
usePrintHelp(texts) { kind, message }, or null, for your own design
  • Failed prints: print gives null and sets error, so a click handler needs no try.
  • autoConnect connects as soon as the provider is on the page, so the questions can show right away.
  • usePrinters loads once connected, and doesn’t update by itself: call refresh from a click.
  • usePreview asks again when the document’s content changes, after a short wait, so typing doesn’t ask on every key.
  • Next.js: build documents anywhere, including server components. TaprelProvider and PrintHelp are already client code. A component of yours that calls a hook needs "use client".
  • Other languages: the customer’s messages are in English. Pass your own for any of them:
import { PrintHelp } from "@taprel/react";

export function FrenchHelp() {
  return <PrintHelp texts={{ "agent-not-running": "Lancez l'application d'impression." }} />;
}

Vue

@taprel/vue needs Vue 3.3 or newer. Add the plugin, as in the Quick start. The results are refs: templates read them directly, and scripts use .value.

Name What it gives you
createTaprel(options) The plugin. Takes the client’s options, autoConnect, or your own client as printClient. Its client works outside components, such as in a store
usePrint() print, printPdf, printRaw, isPrinting, error, result, warnings, reset
useTaprel() status, error, agent, isConnected, connect, disconnect, client
usePrinters({ kind }) printers, isLoading, error, refresh
usePreview(doc, { printer, printerKind, delayMs }) src, preview, isLoading, error. doc can be a function that builds the document, so the preview follows your data
PrintHelp The customer’s next step. Takes texts, downloadUrl, downloadText
usePrintHelp(texts) { kind, message }, or null, for your own design

Failed prints, autoConnect, usePrinters and usePreview work as in React. For Nuxt, add the plugin in app/plugins/taprel.ts. Nothing connects on the server, only in the browser:

import { createTaprel } from "@taprel/vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(createTaprel());
});

PrintHelp’s kind is one of answer-browser, answer-agent, browser-blocked, agent-not-running, website-refused or other, in both packages.