2.0 Getting Started

Compatibility

• ✅ 2.0 | ⛔ 1.9 | ...

Background

• QZ Tray ships with a sample.html page to demonstrate its features.
• The sample.html is bundled with the desktop software located at
• QZ Tray, Advanced, Open File Location, demo
• This guide assumes you have a physical or virtual printer attached.
• For raw printing, make sure to follow the Linux, Windows or Mac raw printer setup guide, respectively.

Summary

In this tutorial, we will break down the API into a simplistic, bare-bones example to illustrate what is needed to print from a webpage with QZ Tray.

The Code

1. In the demo folder of QZ Tray (QZ Tray/demo/js) there are several JavaScript files. Two of these are essential for QZ Tray 2.0.

   File	Description	Required
   js/dependencies/rsvp-3.1.0.min.js	ECMAScript 6 Promise lib	✅ Yes, unless overriden.
   js/dependencies/sha-256.min.js	SHA-256 hashing lib	✅ Yes, unless overriden.
   js/qz-tray.js	QZ Tray websocket wrapper	✅ Yes

   <script type="text/javascript" src="js/dependencies/rsvp-3.1.0.min.js"></script>
   <script type="text/javascript" src="js/dependencies/sha-256.min.js"></script>
   <script type="text/javascript" src="js/qz-tray.js"></script>

1. This next portion of the code deploys QZ Tray by calling qz.websocket.connect() to bind to a local websocket instance of the running software.

   Connect

   qz.websocket.connect().then(function() {
      alert("Connected!");
   });

   💡 Note: To keep trying the connection after failure:

   • qz.websocket.connect({ retries: 5, delay: 1}).then(...);.
   • Need to launch QZ from the click of a button? You can do that too.

2. This next code snippet calls qz.printer.find(..) to find a printer named "zebra". This can only be called after a successful connection.

   Find Printer

   qz.printers.find("zebra").then(function(found) {
      alert("Printer: " + found);
   });

3. Finally, we send the printer some data using qz.print(...). This can only be called after a successful connection.

   Send Data

   var config = qz.configs.create("Zebra LP2844-Z");               // Exact printer name from OS
   var data = ['^XA^FO50,50^ADN,36,20^FDRAW ZPL EXAMPLE^FS^XZ'];   // Raw commands (ZPL provided)
   
   qz.print(config, data).then(function() {
      alert("Sent data to printer");
   });

4. That's it! Now chain them all together.

   qz.websocket.connect().then(function() { 
      return qz.printers.find("zebra")               // Pass the printer name into the next Promise
   }).then(function(printer) {
      var config = qz.configs.create(printer);       // Create a default config for the found printer
      var data = ['^XA^FO50,50^ADN,36,20^FDRAW ZPL EXAMPLE^FS^XZ'];   // Raw ZPL
      return qz.print(config, data);
   }).catch(function(e) { console.error(e); });

What Next?

• Looking for another language? See our Raw Printing tutorial for ZPL, EPL, ESC/P or try our Generic method.
• QZ Tray can do much more than print raw commands. It can print:
• PDFs, HTML, Images
• It can send and receive data from:
• USB and Serial attached devices
• It can print silently, but only if messages are digitally signed.