qr.js

JavaScript library for generating QR codes

qr.js is a pure JavaScript library for generating QR codes utilising HTML5 technology.

Originally based on jsqrencode but with cleaner safer code and not to mention a new simple and understandable API.

This library requires HTML5 to work as its <canvas> element is used to render the QR code.

Install

Install using the package manager for your desired environment(s):

# for node.js:
$ npm install qr-js
# OR; for the browser:
$ bower install qr-js

Examples

In the browser:

<html>
  <body>
    <canvas id="qr-code"></canvas>
    <script src="/path/to/qr.min.js"></script>
    <script>
      qr.canvas({
        canvas: document.getElementById('qr-code'),
        value: 'http://neocotic.com/qr.js'
      });
    </script>
  </body>
</html>

In node.js:

var qr = require('qr-js');

qr.saveSync('http://neocotic.com/qr.js', 'qrcode.png');

API

Standard Data

The following configuration data options are recognised by all of the core API methods (all of which are optional):

Property Description Default
background Background colour to be used White (i.e. #fff)
canvas <canvas> element in which the QR code should be rendered Creates a new element
foreground Foreground colour to be used Black (i.e. #000)
level ECC level to be applied (e.g. L, M, Q, H) Low (i.e. L)
size Module size of the generated QR code (e.g. 1-10 — actual size of the QR code symbol and is scaled to 25 pixels) 4
value Value to be encoded in the generated QR code Empty string (i.e. "")

What is ECC?

ECC (Error Correction Capacity) levels represent the amount of data that can be restored if the QR code symbol is smudged or damanged. There are four ECC levels ranging from L (smallest) to H (best);

L
Low — Approx. 7% of codewords can be restored
M
Medium — Approx. 15% of codewords can be restored
Q
Quartile — Approx. 25% of codewords can be restored
H
High — Approx. 30% of codewords can be restored

canvas([data|value])

Renders a QR code in an HTML5 <canvas> element for a given value. 

// Render the QR code on a newly created canvas element
var canvas = qr.canvas('http://neocotic.com/qr.js');
document.body.appendChild(canvas);
// Re-render the QR code on an existing element
qr.canvas({
  canvas: canvas,
  value: 'https://github.com/neocotic/qr.js'
});

image([data|value])

Renders a QR code in an HTML <img> element for a given value. 

// Render the QR code on a newly created img element
var img = qr.image('http://neocotic.com/qr.js');
document.body.appendChild(img);
// Re-render the QR code on an existing element
qr.image({
  image: img,
  value: 'https://github.com/neocotic/qr.js'
});
Additional Data
As well as the Standard Data, image(1) also accepts these additional data options
Property Description Default
image <img> element in which the QR code should be rendered Creates a new element
mime MIME type to process the QR code image PNG (i.e. image/png)

save([data|value][, path], callback)

Saves a QR code, which has been rendered for a given value, to the user's file system. 

// Render a QR code to a PNG file
qr.save('http://neocotic.com/qr.js', 'qr.png', function(err) {
  if (err) throw err;

  // ...
});
// Render a QR code to a JPEG file
qr.save({
  mime: 'image/jpeg',
  path: 'qr.jpg',
  value: 'https://github.com/neocotic/qr.js'
}, function(err) {
  if (err) throw err;

  // ...
});
Heads up! Currently, in the browser, this just does it's best to force a download prompt. We will try to improve on this in the future.
Additional Data
As well as the Standard Data, save(3) also accepts these additional data options
Property Description Default
mime MIME type to process the QR code image PNG (i.e. image/png)
path¹ Path to which the QR code should be saved Required if not specified as an argument
¹ Ignored in browsers

saveSync([data|value][, path])

Synchronous save(3).

toDataURL([data|value])

Returns a data URL for rendered QR code. This is a convenient shorthand for dealing with the native HTMLCanvasElement.prototype.toDataURL function. 

console.log(qr.toDataURL('http://neocotic.com/qr.js')); // "data:image/png;base64,iVBORw0KGgoAAAA..."
console.log(qr.toDataURL({
  mime: 'image/jpeg',
  value: 'https://github.com/neocotic/qr.js'
})); // "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
Additional Data
As well as the Standard Data, toDataURL(1) also accepts these additional data options
Property Description Default
mime MIME type to process the QR code image PNG (i.e. image/png)

Miscellaneous

noConflict()

Returns qr in a no-conflict state, reallocating the qr global variable name to its previous owner, where possible.

This is really just intended for use within a browser.

<script src="/path/to/conflict-lib.js"></script>
<script src="/path/to/qr.min.js"></script>
<script>
  var qrNC = qr.noConflict();
  // Conflicting lib works again and use qrNC for this library onwards...
</script>

VERSION

The current version of qr.

console.log(qr.VERSION); // "1.1.4"

Canvas Support

For browser users; their browser must support the HTML5 canvas element or the API will throw an error immediately.

For node.js users; qr.js heavily depends on node-canvas to support the HTML5 canvas element in the node.js environment. Unfortunately, this library is dependant on Cairo, which is not managed by npm. Before you are able to install qr.js (and it's dependencies), you must have Cairo installed. Please see the node-canvas wiki for steps on how to do this on various platforms.

Changes

Version 1.1.4

  • #2 Fix padding issues
  • #35 Make the QR-code center-aligned
  • #38 Update node-canvas dependency version to support Node.js v4 and above
View historical changes

Bugs

If you have any problems with this library or would like to see the changes currently in development browse our issues.

Questions?

Take a look at the documentation to get a better understanding of what the code is doing.

If that doesn't help, feel free to follow me on Twitter, @neocotic.

Download View Source