The little QR code scanning library I have been maintaining since 2015 has been getting more attention recently. And with power came responsibilities, bugs, and feature requests. Some of the key features requested by developers were more reliable scanning and the ability to scan different types of bar codes. With version 2.0.0 onwards developers can scan different types of 1D codes (bar codes) and 2D codes (like QR codes or AZTEC).

This article lists out everything new in version 2.x.x. I’ll also list out the new APIs and capabilities that developers can use to integrate a more powerful code scanning capability to their web pages or apps.

Here’s the library I am taking about: mebjas/html5-qrcode, checkout demo at qrcode.minhazav.dev

Star Fork Issue Discuss

What’s new in version 2.x.x

Latest: GitHub tag (latest by date) Codacy Badge Build Status

  1. Ability to scan different kinds of 1D codes and 2D codes.
    • See all supported formats here.
    • Scanned format type and the name returned in the success callback.
  2. More reliable code scanning, fixing issues like issue#134, issue#63, issue#140.
    • Both (1) & (2) were achieved by migrating the decoding library from Lazarsoft's library to Zxing-js.
  3. [Minor] Library now reports more granular errors to reduce debugging time for developers.
    • For example, if the library is used in HTTP url, the exact issue will be reported.

Code health fixes

  1. Entire code migrated to Typescript for scalable & less error-prone development.

  2. Several code health issues fixed based on Codacy report and now we have grade A on Codacy - , tracking issue for this refactor

Check out changelog since Version 2.0.0 for more clarity.

Using the library

The library exposes two main classes:

  • Html5QrcodeScanner - Use this to set up end to end scanner with UI, built on top of Html5Qrcode.
    • Takes care of building full user interface
    • Supports scanning using a web-cam or camera on the device with real-time camera feeds.
    • Support scanning local images on the device.
  • Html5Qrcode - lower-level library, exposes APIs to build your code scanner.

Integrating code scanner using Html5QrcodeScanner

Follow the steps below to integrate QR code or barcode scanning capabilities into your web application:

Install the library

You could install the library using npm or load it directly using some CDNS like unpkg

Install using npm

npm install --save-dev html5-qrcode

Load latest library from unpkg or other CDNs

<!-- include the library -->
<script src="https://unpkg.com/html5-qrcode@2.0.9/dist/html5-qrcode.min.js"></script>

Add placeholder HTML element

Add a placeholder HTML element to your web page. The scanning UI would be rendered in this element. Give it appropriate stylings like width or height.

<div id="qr-reader" style="width: 600px"></div>

Initialize in javascript

Now you can set up the scanner with these 4 lines of code.

function onScanSuccess(decodedText, decodedResult) {
    console.log(`Code scanned = ${decodedText}`, decodedResult);
}
var html5QrcodeScanner = new Html5QrcodeScanner(
	"qr-reader", { fps: 10, qrbox: 250 });
html5QrcodeScanner.render(onScanSuccess);

Demo

Notes:

  • You can customize the scanner by passing a different config object - read more.
  • The success callback has the following interface (/src/core.ts)
/** Format of detected code. */
interface QrcodeResultFormat {
    format: Html5QrcodeSupportedFormats;
    formatName: string;
}

/** Detailed scan result. */
interface QrcodeResult {
    text: string;
    format: QrcodeResultFormat,
}

/** QrCode result object. */
interface Html5QrcodeResult {
    decodedText: string;
    result: QrcodeResult;
}

type QrcodeSuccessCallback
    = (decodedText: string, result: Html5QrcodeResult) => void;

Html5Qrcode interface

If you want to build your user interface, you can make use of the public APIs exposed by Html5Qrcode class:

class Html5Qrcode {
    constructor(elementId: string, config: Html5QrcodeFullConfig) {}

    /** Start scanning. */
    start(cameraIdOrConfig: Html5QrcodeIdentifier,
        configuration: Html5QrcodeCameraScanConfig | undefined,
        qrCodeSuccessCallback: QrcodeSuccessCallback | undefined,
        qrCodeErrorCallback: QrcodeErrorCallback | undefined,
    ): Promise<null> {}

    /** Stop scanning. */
    stop(): Promise<void> {}

    /** Clear the rendered surface. */
    clear(): void {}

    /** Scan a file. */
    scanFile(
        imageFile: File,
        showImage?: boolean): Promise<string> {}

    /** Returns list of cameras in the device, invokes permission request. */
    static getCameras(): Promise<Array<CameraDevice>> {}
}

All supported formats

These are the different code formats now supported by the library, with examples:

Code Example
QR Code
AZTEC
CODE_39
CODE_93
CODE_128
MAXICODE
ITF
EAN_13
EAN_8
PDF_417
RSS_14
RSS_EXPANDED
UPC_A
UPC_E
DATA_MATRIX

Future plans

How to contribute

If you are excited or interested you can contribute to this project by:

  • If you find compatibility issues with a certain browser, create an issue here.
  • Raising issues for bugs faced, at Github issue page for the project. Feel free to add some related interesting discussions which could be taken up as work-item.
  • Sending a Pull Request for bugs fixed by you.
  • Rating the project with stars and shares.