2.1 Pixel Printing

Compatibility

✅ 2.1 | ✅ 2.0 | ⛔ 1.9 | ...

Background

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, try using a PDF or XPS writer.

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

HTML Printing

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

2.1

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.0

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

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

2.1

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); });

2.0

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

A print parameter can be supplied to force a particular HTML page width

2.1

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 }
}];
qz.print(config, data).catch(function(e) { console.error(e); });

2.0

var config = qz.configs.create("Printer Name");
var data = [{
   type: 'html',
   format: 'file', // or 'plain' if the data is raw HTML
   data: 'assets/html_sample.html',
   options: { pageWidth: 8 }
}];
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
- 💡 Older Ubuntu versions can get Oracle Java 8 + JavaFX here: http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html

PDF Printing

QZ Tray 2.0 allows printing PDF files directly to a printer using Apache PDFBOX.

⚠️ Warning: Mac users may need to specify a density per #155

How to print a PDF file

2.1

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); });

2.0

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

Base64 PDF

How to print a base64 PDF

2.1

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); });

2.0

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

Image Printing

How to print an image

2.1

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

2.0

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

Base64 Image

How to print a base64 image

2.1

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); });

2.0

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

Advanced Printing

In this section, we will focus on creating a config with various options. The syntax between 2.0 and 2.1 are identical for the config options.

Below is the boiler plate we will be using. Remember, the data will have different syntax between 2.0 and 2.1

function printStuff() {
  var config = qz.configs.create();
  var data = [{
  }];

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

For simplicity, we will not be changing the data between examples. Use the appropriate syntax for your version.

2.1

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

2.0

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

Page Size

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.

Dymo LabelWriter

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 = [{ 
// use appropriate config from above for your version
}];

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

Margins

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, right, bottom, left] });
var data = [{ 
// use appropriate config for your version from above
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Image Interpolation

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 = [{ 
// use appropriate config for your version from above 
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Density

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: "600" });  // force 600dpi
var data = [{ 
// use appropriate config from above for your version
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Custom Job Name

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 = [{ 
// use appropriate config from above for your version
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Define Printer Tray

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

Note: This feature is only available in 2.1 and onward.

var config = qz.configs.create("Printer Name", { printerTray: '1' });
var data = [{ 
// use appropriate config from above for your version
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Disable Autoscale

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 = [{ 
// use appropriate config from above for your version
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Rasterize

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.

⚠️ 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 = [{ 
// use appropriate config from above for your version
}];
qz.print(config, data).catch(function(e) { console.error(e); });

Chaining Requests

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');            ////// First 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
});

Promise Loop

Using a Promise Loop, we can defer items (printers, data)

So that different chunks of data can be sent to different printers
So that an arbitrary (non-fixed) amount of data can be sent to a printer

function promiseLoop() {
    var data = [
        { "type": "pdf", "data": "assets/sample_pdf1.pdf" },
        { "type": "pdf", "data": "assets/sample_pdf2.pdf" },
        { "type": "pdf", "data": "assets/sample_pdf3.pdf" },
        { "type": "pdf", "data": "assets/sample_pdf3.pdf" },
        { "type": "pdf", "data": "assets/sample_pdf5.pdf" }
    ];
    var configs = [
        { "printer": "HP LaserJet M605" },
        { "printer": "HP LaserJet M605" },
        { "printer": "HP LaserJet M605" },
        { "printer": "HP LaserJet M605" },
        { "printer": "HP LaserJet M605" }
    ];
    var chain = [];

    for(var i = 0; i < data.length; i++) {
        (function(i_) {
            //setup this chain link
            var link = function() {
                return qz.printers.find(configs[i_].printer).then(function(found) {
                    return qz.print(qz.configs.create(found), [data[i_]]);
                });
            };

            chain.push(link);
        })(i);
        //closure ensures this promise's concept of `i` doesn't change
    }

    //can be .connect or `Promise.resolve()`, etc
    var firstLink = new RSVP.Promise(function(r, e) { r(); });

    var lastLink = null;
    chain.reduce(function(sequence, link) {
        lastLink = sequence.then(link);
        return lastLink;
    }, firstLink);

    //this will be the very last link in the chain
    lastLink.catch(function(err) {
        console.error(err);
    });
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly