qr.js

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.

Handling QR codes

All the data used by qr.js are optional and you can choose to provide no information at all if you wish. The API has two simple methods that take a single object argument that can contain the following values;

• background - The background colour to be used
• Optional: White (#fff) is used by default
• canvas - A <canvas> element in which the QR code should be rendered
• Optional: Creates a new <canvas> element by default
• foreground - The foreground colour to be used
• Optional: Black (#000) is used by default
• image - An <img> element in which the QR code should be rendered
• Optional: Creates a new <img> element by default
• Only used by qr.image
• level - The ECC level to be applied (L, M, Q, H)
• Optional: The L ECC level is used by default
• path - The path to which the QR code should be saved
• This property is only used by qr.save
• This property is only required when running outside of the browser environment and is ingored otherwise
• size - The module size of the generated QR code (1-10)
• Optional: 4 is used by default
• This is the actual size of the QR code symbol and is scaled to 25 pixels (e.g. 1 = 25px, 3 = 75px)
• value - The value to be encoded in the generated QR code
• Optional: An empty string is used by default

Using <img>

qr.image([data|value][, callback(error, image)])

Returns either a new <img> element containing the generated QR code or the value of data.image if it was specified.

Example

Add an image of a rendered QR code to a page.

window.addEventListener('onload', function() {
  // Get image for rendered QR code
  var image = qr.image({
      level: 'H'
    , size: 4
    , value: 'http://neocotic.com/qr.js'
  })
  // Check image was returned (may not have been if browser doesn't support the
  // HTML5 canvas element)
  if (image) {
    // Add image to page
    document.body.appendChild(image)
  }
})

Using <canvas>

qr.canvas([data|value][, callback(error, canvas)])

Returns either a new <canvas> element containing the generated QR code or the value of data.canvas if it was specified.

Example

Render the QR code in an existing canvas on a page.

window.addEventListener('onload', function() {
  // Render the QR code in <canvas id="qr"/>
  qr.canvas({
      canvas: document.getElementById('qr')
    , level: 'L'
    , size: 4
    , value: 'http://neocotic.com/qr.js'
  })
})

Save As...

qr.save([data|value][, path][, callback(error)])

Generates a QR code and saves it to either the location specified, unless the script is running in the browser, in which case the user is prompted to specify a location and file name before it is downloaded.

Example

Prompt the user to download the generated QR code.

window.addEventListener('onload', function() {
  // Prompt user to save image as file
  qr.save('http://neocotic.com/qr.js')
})

Data URL

qr.toDataURL([data|value][, callback(error, url)])

Return the data URL for the generated QR code.

Example

Show an alert containing the data URL for the generated QR code.

window.addEventListener('onload', function() {
  // Get data URL for QR code
  var url = qr.toDataURL('http://neocotic.com/qr.js')
  // Check URL was returned (may not have been if browser doesn't support the
  // HTML5 canvas element)
  if (url) {
    // Alert user with the URL
    alert(url)
  }
})

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 - Approx. 7% of codewords can be restored
• M - Approx. 15% of codewords can be restored
• Q - Approx. 25% of codewords can be restored
• H - Approx. 30% of codewords can be restored

Miscellaneous

The qr.js API exposes some properties and methods which may only be useful to users in special cases.

qr.noConflict([callback(error)])

Relinquish qr.js' control of the qr global variable. If another library uses this variable calling this method will reassign it back to that library.

qr.VERSION

The current version of qr.js.

Changes

Version 1.0.3

• #3 Rename QRCode to qr
• #3 Remove all deprecated methods
• #4 Reformat code and add additional, along with some original, code comments
• #6 Add support for Node.js, CommonJS and Ender
• #6 Add optional callback functionality to API methods
• #7 Allow data arguments to be an object or string value
• #8 Add VERSION property to the API
• #8 Add toDataURL, save and noConflict methods to the API
• Now distributed under the MIT License

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.