JSPM

  • Created
  • Published
  • Downloads 167871
  • Score
    100M100P100Q166041F
  • License Apache-2.0

a cross platform HTML5 QR Code reader

Package Exports

  • html5-qrcode

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (html5-qrcode) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Html5-QRCode

A cross-platform HTML5 QR code reader. Use this light-weight Javascript library (52 Kb) to add QR Code scanning capability in your web application.

Supported platforms

Working on adding support for more and more platforms. If you find a platform or browser where the library is not working please feel free to file an issue. Check the demo link to test out.

Legends
  • Means supported
  • Means work in progress to add support

PC / Mac

Firefox
Firefox
Chrome
Chrome
Safari
Safari
Opera
Opera
Edge
Edge

Android

Chrome
Chrome
Firefox
Firefox
Edge
Edge
Opera
Opera
Opera-Mini
Opera Mini
UC
UC

IOS

Safari
Safari
Chrome
Chrome
Firefox
Firefox
Edge
Edge

Apparently, Webkit for IOS is used by Chrome, Firefox, and other browsers in IOS and they do not have webcam permissions yet. There is an ongoing issue on fixing the support for iOS - issue/14

Description - View Demo

This is a cross-platform javascript library to create a QRcode reader for HTML5 compatible browser.

Supports:

  • Querying all camera in the device (With user permissions)
  • Using any camera for scanning QR Code.

How to use?

For full information read this article.

Add an element you want to use as placeholder for QR Code scanner

<div id="reader"></div>

Add minified/html5-qrcode.min.js in your web page.

I would recommend using the minified version as it's transformed to standard javascript. The html5-qrcode.js is written with ECMAScript and may not be supported in older version of the browsers. I wrote in this as it's easier to maintain!

<script src="./minified/html5-qrcode.js"></script>
<!--
  Or use directly from Github

<script src="https://raw.githubusercontent.com/mebjas/html5-qrcode/master/minified/html5-qrcode.min.js"></script>
-->

To get a list of supported cameras, query it using static method Html5Qrcode.getCameras(). This method returns a Promise with list of devices supported in format { id: "id", label: "label" }.

// This method will trigger user permissions
Html5Qrcode.getCameras().then(cameras => {
  /**
   * devices would be an array of objects of type:
   * { id: "id", label: "label" }
   */
  if (devices && devices.length) {
    var cameraId = devices[0].id;
    // .. use this to start scanning.
  }
}).catch(err => {
  // handle err
});

Once you have the camera id from device.id, start camera using Html5Qrcode#start(..). This method returns a Promise with Qr code scanning initiation.

const html5QrCode = new Html5Qrcode(/* element id */ "reader");
html5QrCode.start(
  cameraId, 
  {
    fps: 10,    // Optional frame per seconds for qr code scanning
    qrbox: 250  // Optional if you want bounded box UI
  },
  qrCodeMessage => {
    // do something when code is read
  },
  errorMessage => {
    // parse error, ignore it.
  })
.catch(err => {
  // Start failed, handle it.
});

To stop using camera and thus stop scanning, call Html5Qrcode#stop() which returns a Promise for stopping the video feed and scanning.

html5QrCode.stop().then(ignore => {
  // QR Code scanning is stopped.
}).catch(err => {
  // Stop failed, handle it.
});

Demo

blog.minhazav.dev/research/html5-qrcode.html

For more information

Check this article on how to use this library HTML5 QR Code scanning - launched v1.0.1 without jQuery dependency and refactored Promise based APIs.

Screenshots

screenshot
Figure: Screenshot from Google Chrome running on Macbook Pro

Documentation

Following methods are available in this library

class Html5Qrcode {
  /**
   * Returns a Promise with list of all cameras supported by the device.
   * 
   * The returned object is a list of result object of type:
   * [{
   *      id: String;     // Id of the camera.
   *      label: String;  // Human readable name of the camera.
   * }]
   */
  static getCameras() // Returns a Promise

  /**
   * Initialize QR Code scanner.
   * 
   * @param {String} elementId - Id of the HTML element. 
   */
  constructor(elementId) {}

  /**
   * Start scanning QR Code for given camera.
   * 
   * @param {String} cameraId Id of the camera to use.
   * @param {Object} config extra configurations to tune QR code scanner.
   *  Supported Fields:
   *      - fps: expected framerate of qr code scanning. example { fps: 2 }
   *          means the scanning would be done every 500 ms.
   *      - qrbox: width of QR scanning box, this should be smaller than
   *          the width and height of the box. This would make the scanner
   *          look like this:
   *          ----------------------
   *          |********************|
   *          |******,,,,,,,,,*****|      <--- shaded region
   *          |******|       |*****|      <--- non shaded region would be
   *          |******|       |*****|          used for QR code scanning.
   *          |******|_______|*****|
   *          |********************|
   *          |********************|
   *          ----------------------
   * @param {Function} qrCodeSuccessCallback callback on QR Code found.
   *  Example:
   *      function(qrCodeMessage) {}
   * @param {Function} qrCodeErrorCallback callback on QR Code parse error.
   *  Example:
   *      function(errorMessage) {}
   * 
   * @returns Promise for starting the scan. The Promise can fail if the user
   * doesn't grant permission or some API is not supported by the browser.
   */
  start(cameraId,
      configuration,
      qrCodeSuccessCallback,
      qrCodeErrorCallback) {}  // Returns a Promise

  /**
   * Stops streaming QR Code video and scanning. 
   * 
   * @returns Promise for safely closing the video stream.
   */
  stop() {} // Returns a Promise
}       

Extra optional configuration in start() method

This is a configuration for the QR code scanning which can effect both scanning behavior and UI. There are two optional properties right now, if you don't want them you can just pass an empty object {}.

fps - Integer, Example = 10

A.K.A frame per seconds, the default value for this is 2 but it can be increased to get faster scanning. Increasing too high value could affect performance. Value >1000 will simply fail.

qrbox - Integer, Example = 250

Use this property to limit the region of the viewfinder you want to use for scanning. The rest of the viewfinder would be shaded. For example by passing config { qrbox : 250 }, the screen will look like:

If you do not pass any value, the whole viewfinder would be used for scanning. Note: this value has to be smaller than the width and height of the QR code HTML element.

Credits

The decoder used for the QRcode reading is from LazarSoft https://github.com/LazarSoft/jsqrcode