react-qztray

React hooks for seamless integration with QZ Tray — the browser-to-desktop print connector.

---

Requirements

• QZ Tray desktop application running on the user's machine (download)
• React 18 or 19
• A backend endpoint to sign QZ Tray requests (required for production use)

Tutorials

• How to sign QZ Tray requests in Node.js
• How to generate a self-signed certificate for QZ Tray

---

Installation

npm install react-qztray
# or
pnpm add react-qztray

---

Quick start

1. Wrap your app with QzTrayProvider

import { QzTrayProvider } from 'react-qztray';

export const Root = () => (
  <QzTrayProvider
    certificate="-----BEGIN CERTIFICATE-----\nYOUR_CERT_HERE\n-----END CERTIFICATE-----"
    signatureAlgorithm="SHA512"
    signaturePromise={(toSign) => (resolve) => {
      fetch('/api/sign', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ toSign }),
      })
        .then((res) => res.text())
        .then(resolve);
    }}
  >
    <App />
  </QzTrayProvider>
);

2. Connect and print

import { useQzTray, useQzPrint } from 'react-qztray';

const PrintButton = () => {
  const { isConnected, connect } = useQzTray();
  const { print, isPrinting } = useQzPrint();

  const handlePrint = async () => {
    if (!isConnected) await connect();

    print({
      printer: 'ZDesigner',
      config: { size: { width: 100, height: 150 }, units: 'mm' },
      data: [{ type: 'pixel', format: 'html', flavor: 'plain', data: '<h1>Hello!</h1>' }],
    });
  };

  return (
    <button onClick={handlePrint} disabled={isPrinting}>
      {isPrinting ? 'Printing...' : 'Print'}
    </button>
  );
};

---

API

QzTrayProvider

Provides QZ Tray context to all child hooks. Place it at the root of your app.

Prop	Type	Required	Description
certificate	string | (() => Promise<string>)	✓	Public PEM certificate from QZ Tray's signing tool. Accepts a string or an async function that fetches it.
signaturePromise	PromiseFactory	✓	Factory function that signs the request. Should call your backend.
signatureAlgorithm	"SHA1" | "SHA256" | "SHA512"		Signing algorithm. Defaults to "SHA512".
wsOptions	ConnectOptions		WebSocket connection options (host, port, keepAlive, retries, delay).
autoConnect	boolean		Connect to QZ Tray automatically on mount. Defaults to false.
onConnect	() => void		Called when the connection is established.
onDisconnect	() => void		Called when the connection is closed.
onError	(error: unknown) => void		Called on connection error.

---

useQzTray

Access connection state and controls. Must be used inside QzTrayProvider.

const { isConnected, isConnecting, error, connect, disconnect } = useQzTray();

Return	Type	Description
isConnected	boolean	Whether QZ Tray is currently connected.
isConnecting	boolean	Whether a connection attempt is in progress.
error	unknown	Last connection error, or null.
connect	() => Promise<void>	Open the WebSocket connection.
disconnect	() => Promise<void>	Close the WebSocket connection.

---

useQzPrint

Send print jobs to any printer visible to QZ Tray. Must be used inside QzTrayProvider.

const { print, isPrinting, error } = useQzPrint();

Return	Type	Description
print	(options: IPrintOptions) => Promise<void>	Send a print job. Connects automatically if not connected.
isPrinting	boolean	Whether a print job is in progress.
error	unknown	Last print error, or null.

IPrintOptions

Option	Type	Required	Description
printer	string	✓	Printer name as it appears in the OS.
data	PrintData[]	✓	Array of print data objects.
config	PrinterOptions		Paper size, units, density, orientation, etc.
autoDisconnect	boolean		Disconnect after the job completes. Defaults to true.

---

Examples

See the examples/ directory for complete usage examples:

• 01-basic-setup.tsx — Provider setup with inline and async certificate
• 02-connection.tsx — Connection status UI and autoConnect
• 03-print-html.tsx — Print HTML content as a pixel job
• 04-print-pdf.tsx — Print PDF from URL or base64
• 05-print-raw.tsx — Raw ZPL and ESC/POS commands
• 06-multiple-jobs.tsx — Chain multiple jobs without disconnecting

---

Playground

A Vite dev app is included for local testing.

pnpm install
pnpm playground

Open http://localhost:5173, paste your certificate and signature endpoint, and send test print jobs directly from the browser.

---

Contributing

Contributions are more than welcome! Whether it's a bug report, feature request, or a pull request — all input is appreciated.

1. Fork the repo and create your branch from main
2. Install dependencies with pnpm install
3. Make your changes and add tests where applicable
4. Run pnpm lint, pnpm typecheck, and pnpm test before submitting
5. Open a pull request

If you're unsure about something, feel free to open an issue first to discuss it.

---

License

MIT © Juliusz Kowalewski