Documentation

• ✅ 2.2 | ✅ 2.1 | ✅ 2.0* | ⛔ 1.9 | ...

These features may not work with many raw printing devices, such as Zebra, Epson, Citizen printers. The data is sent in Pixel Printing format, which is more common for LaserJet or Deskjet printers. The ZDesigner driver from Zebra allows both raw and pixel printing.

To test these features without a physical printer, use a printer emulator

The following code can be used for Pixel Printing (formerly Postscript Printing) only. If you are unsure what Pixel Printing is, please refer to What is Pixel Printing?

• HTML Printing
  • Multi-Page HTML Printing
• PDF Printing
• Image Printing
• Advanced Pixel Printing
• Specifying Custom Page Size | Dymo LabelWriter
• Specifying Page Orientation
• Overriding Default Margins
• Disabling Auto-Scaling of Content
• Forcing Image Interpolation
• Specifying Custom Job Name
• Specifying Tray Used For Printing
• Double sided printing
• Vector PDF Printing (Disable Image Rasterization)
• Advanced Print Spooling
• Chaining Print Requests
• Queuing Print Requests

1. HTML rendering is done via pure Java in using an embedded webkit browser

   var config = qz.configs.create("Printer Name");
   var data = [{
      type: 'pixel',
      format: 'html',
      flavor: 'file', // or 'plain' if the data is raw HTML
      data: 'assets/html_sample.html'
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

2. An options parameter can be supplied to to signify things including margins, orientation, size, printer language, encoding, etc.

   var config = qz.configs.create("Printer Name", { margins: 2, orientation: 'landscape'});
   var data = [{
      type: 'pixel',
      format: 'html',
      flavor: 'file', // or 'plain' if the data is raw HTML
      data: 'assets/html_sample.html'
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

3. The pageWidth or pageHeight data print parameter can be supplied to force a particular HTML page width or HTML page height:

   Page Width

   Page Height

   var config = qz.configs.create("Printer Name");
   var data = [{
      type: 'pixel',
      format: 'html',
      flavor: 'file', // or 'plain' if the data is raw HTML
      data: 'assets/html_sample.html',
      options: { pageWidth: 8.5 /* pageHeight: 11 */ }
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

   Multi-Page HTML

   Disable autoscaling to allow the HTML content to overflow to a second page.

   var config = qz.configs.create("Printer", { scaleContent: false });
   var data = [{
      type: 'pixel',
      format: 'html',
      flavor: 'file', // or 'plain' if the data is raw HTML
      data: 'assets/html_sample.html'
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

   JavaFX

   • ⚠️ Java 8 + JavaFX is required for high-resolution (>72 dpi) HTML printing.
     • ⚠️ Linux users: By default, JavaFX is NOT included in OpenJDK
   • 💡 We recommend using AdoptOpenJDK 11 for all Operating Systems. We have written an installation tutorial: Upgrading Java

1. How to print a PDF file

   var config = qz.configs.create("Printer Name");
   var data = [{ 
         type: 'pixel',
         format: 'pdf',
         flavor: 'file',
         data: 'assets/pdf_sample.pdf' 
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

1. How to print a base64 PDF

   var config = qz.configs.create("Printer Name");
   var data = [{ 
      type: 'pixel',
      format: 'pdf',
      flavor: 'base64',
      data: 'Ck4KcTYwOQpRMjAzLDI2CkI1LDI2LDAsMUEsMyw3LDE1MixCLCIxMjM0IgpBMzEwLDI2LDAsMywx...' 
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

• There's a long-standing issue with Java and transparency that can cause poor print quality and higher memory utilization when a PDF has transparent layers in it. This issue is perpetuated for low-dpi printers such as 203/300 DPI label printers or 180 DPI receipt printers.

• A workaround for this is to allow QZ Tray to strip out all transparent PDF layers when printing using the ignoreTransparency data print parameter.

  var config = qz.configs.create("Printer Name");
  );
  var data = [{ 
     type: 'pixel',
     format: 'pdf',
     flavor: 'file'
     data: 'assets/pdf_sample.pdf',
     options: { ignoreTransparency: true } // don't print transparent layers; workaround for PDFBOX-4123, PDFBOX-4380
  }];
  qz.print(config, data).catch(function(e) { console.error(e); });

• For systems running Windows and printing to low-dpi printers (e.g. 180 DPI, 203 DPI), fonts can become hard to read due to how Java draws vector fonts on these systems (See issue #503)

• A workaround for this is to allow QZ Tray to revert to the PDFBOX 1.8 font rendering using the altFontRendering data print parameter.

  var config = qz.configs.create("Printer Name");
  );
  var data = [{ 
     type: 'pixel',
     format: 'pdf',
     flavor: 'file'
     data: 'assets/pdf_sample.pdf',
     options: { altFontRendering: true } // use PDFBOX 1.8 font rendering to fix low-dpi fonts
  }];
  qz.print(config, data).catch(function(e) { console.error(e); });

1. Since 2.1.1, a config parameter bounds can be used to crop a PDF. Useful for formats such as USPS labels which were designed for US Letter paper but need to be resized to smaller paper.

   var config = qz.configs.create("Printer Name",
      { units: 'in', bounds: { x: 1.2, y: 1.2, width: 6, height: 4 } }
   );
   var data = [{ 
      type: 'pixel',
      format: 'pdf',
      flavor: 'file'
      data: 'assets/pdf_sample.pdf' 
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

1. Since 2.2.2, a data options.pageRanges parameter can be provided which prints a specific page, select pages or a page range.

   var config = qz.configs.create("Printer Name");
   var data = [{ 
      type: 'pixel',
      format: 'pdf',
      flavor: 'file'
      data: 'assets/multi_page_pdf.pdf',
      options: { pageRanges: "1-3" }
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

1. How to print an image

   var config = qz.configs.create("Printer Name");
   var data = [{ 
     type: 'pixel',
     format: 'image',
     flavor: 'file',
     data: 'assets/img/image_sample.png' 
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

   • Shorthand: { type: 'pixel', data: 'assets/img/image_sample.png' } format and flavor will default to proper values

1. How to print a base64 image

   var config = qz.configs.create("Printer Name");
   var data = [{ 
      type: 'pixel', 
      format: 'image',
      flavor: 'base64',
      data: 'AAAA...==' 
   }];
   qz.print(config, data).catch(function(e) { console.error(e); });

In this section, we will focus on creating a config with various options.

A page size can be set using the config parameter size.

• Both standard and metric sizes are supported. Warning, providing a metric page size will assume the density is in a metric format as well.

The following example illustrates how to print a 2.25in x 1.25in label to a Dymo LabelWriter printer.

• size is provided in inches. Alternatively 57.15mm x 31.75mm can be provided if metric units are desired.
• interpolation is provided to prevent barcode blurring.
• colorType is provided to maximize driver quality compatibility/300dpi dithering.

function printStuff() {
var config = qz.configs.create("Printer Name", {
   size: {width: 2.25, height: 1.25}, units: 'in', 
   colorType: 'grayscale', 
   interpolation: "nearest-neighbor" 
});

var data = [{ 
   type: 'pixel',
   format: 'image', //'pdf'
   flavor: 'file',
   data: 'assets/img/image_sample.png' // 'assets/pdf_sample.pdf'
}];

qz.print(config, data).catch(function(e) { console.error(e); });
}

A config parameter orientation can be provided to change the default page orientation. Valid values are null (auto), portrait, landscape and reverse-landscape.

If no value is provided, QZ Tray will attempt to determine the orientation automatically for the page and paper size.

var config = qz.configs.create("Printer Name", { orientation: 'landscape' });
var data = [{ 
   type: 'pixel',
   format: 'pdf',
   flavor: 'file',
   data: 'assets/img/pdf_sample.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

A config parameter margins can be provided to change the default page margins around the content.

var top = 0.25, right = 0.25, bottom = 0.25, left = 0.25;
var config = qz.configs.create("Printer Name", { margins: { top: top, right: right, bottom: bottom, left: left } });
var data = [{ 
   type: 'pixel',
   format: 'image', //'pdf'
   flavor: 'file',
   data: 'assets/img/image_sample.png' // 'assets/pdf_sample.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

A config parameter interpolation can be provided to change the pixel blending technique used when scaling an image.

var config = qz.configs.create("Printer Name", { interpolation: "nearest-neighbor" });
var data = [{ 
   type: 'pixel',
   format: 'image',
   flavor: 'file',
   data: 'assets/img/image_sample.png'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Not providing a density will cause printing to use the default value for the printer. A config parameter density can be provided to change the DPI, dots/mm or dots/cm respectively.

// var config = qz.configs.create("Printer Name", { units: "in", density: "best" });  // select best quality (slowest print speed) density automatically
// var config = qz.configs.create("Printer Name", { units: "in", density: "draft" });  // select poorest quality (fastest print speed) automatically
var config = qz.configs.create("Printer Name", { units: "in", density: "600" });  // force 600dpi
var data = [{ 
   type: 'pixel',
   format: 'image', //'pdf'
   flavor: 'file',
   data: 'assets/img/image_sample.png' // 'assets/pdf_sample.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

A config parameter copies can be provided to send the specified pixel content multiple times.

var config = qz.configs.create("Printer Name", { copies: 4 });

var data = [{ 
   type: 'pixel',
   format: 'pdf'
   flavor: 'file',
   data: 'assets/pdf_sample.pdf'
}];;

qz.print(config, data).catch(function(e) { console.error(e); });

A config parameter colorType can be provided to specify if a document is requested to print in black & white or color. The default is color, regardless of what the OS is set to. If the OS preference is preferred, provide default instead. (Since 2.2.4).

var config = qz.configs.create("Printer Name", { colorType: "grayscale" }); // or "color", "blackwhite"

var data = [{ 
   type: 'pixel',
   format: 'pdf',
   flavor: 'file',
   data: 'assets/pdf_sample.pdf'
}];;

qz.print(config, data).catch(function(e) { console.error(e); });

A config parameter jobName can be provided to change the name listed in the print queue.

var config = qz.configs.create("Printer Name", { jobName: "Receipt #123456" });
var data = [{ 
   type: 'pixel',
   format: 'image', //'pdf'
   flavor: 'file',
   data: 'assets/img/image_sample.png' // 'assets/pdf_sample.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

To fetch the available trays from all printers, use qz.printers.details(...), and iterate over the resulting printer.trays array.

qz.printers.details().then(function(data) {
   data.forEach(function(printer) {
      console.log(printer.name, printer.trays || "(None)");
   });
});

A config parameter printerTray can be provided to specify the destination tray or cartridge used for printing.

var config = qz.configs.create("Printer Name", { printerTray: 1 });
// or
config = var config = qz.configs.create("Printer Name", { printerTray: 'Tray 1' });
var data = [{ 
   type: 'pixel',
   format: 'image', //'pdf'
   flavor: 'file',
   data: 'assets/img/image_sample.png' // 'assets/pdf_sample.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

For printers that support it, QZ Tray is capable of printing duplex using the config. Valid values: true, false, 'one-sided', 'duplex', 'long-edge', 'tumble', 'short-edge'.

Most printers will use long-edge by default when enabled. Adjust as needed.

var config = qz.configs.create("Printer Name", { duplex: true });
var data = [{ 
   type: 'pixel',
   format: 'pdf',
   flavor: 'file',
   data: 'path/to/my_multiple_page_document.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

By default, content is automatically scaled to the destination page size. This is done as a courtesy to take out the guesswork in fitting the content to the media. A config parameter scaleContent can be forced to prevent auto-scaling.

var config = qz.configs.create("Printer Name", { scaleContent: "false" });  // do not stretch image to page width
var data = [{ 
   type: 'pixel',
   format: 'image', //'pdf'
   flavor: 'file',
   data: 'assets/img/image_sample.png' // 'assets/pdf_sample.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

In some cases, rather than rasterizing print output, the vector version is preferred. This can have both quality as well as performance benefits during the printing process. A config parameter rasterize can be forced to prevent software rasterization prior to printing. rasterize:false is the default behavior in 2.1.

• ⚠️ This feature is currently only effective with PDF printing, which can cause hard-crashes on OS X, use this with caution!

var config = qz.configs.create("Printer Name", { rasterize: "false" });  // use vector rendering
var data = [{ 
   type: 'pixel',
   format: 'image', //'pdf'
   flavor: 'file',
   data: 'assets/img/image_sample.png' // 'assets/pdf_sample.pdf'
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Since 2.1.3, large PDF documents can be split into multiple, smaller documents by using spool.size. This is useful to lessen the time between spooling and printing, as most printers will print spooled documents first.

var config = qz.configs.create("Printer Name", { spool: { size: 10 } });
var data = [{ 
   type: 'pixel',
   format: 'pdf',
   flavor: 'file'
   data: 'assets/some_huge_pdf.pdf' 
}];;

qz.print(config, data).catch(function(e) { console.error(e); });
}

Print requests can be chained together to print several documents at once, or to print to several different printers.

var config = qz.configs.create();
var data = [{ type: 'image', data: null, }];

data.data = 'assets/img/my_first_image.png';       ////// First document
config.setPrinter('First Printer');                ////// First printer
qz.print(config, data)

.then(function() {
   data.data = 'assets/img/my_second_image.png';   ////// Second document
   config.setPrinter('Second Printer');            ////// Second printer
   return qz.print(config, data);
})

.then(function() {
   data.data = 'assets/img/my_third_image.png';    ////// Third document
   config.setPrinter('Third Printer');             ////// Third printer
   return qz.print(config, data);
})

.catch(function(e) {
   console.error(e);                // Exceptions throw all the way up the stack
});

Looping multiple configs and multiple data objects is now built-in to the 2.1 API. More information here.