html5-qrcode

The library is compatible with several modern web frameworks. Examples and integrations are available for:

• Vanilla HTML5
• VueJs
• ElectronJs
• React (via @scanapp-org/html5-qrcode-react)
• Lit

To build the library for development or production:

1. Install dependencies: npm install.
2. Build JavaScript output: npm run-script build (or npm run-script build-windows on Windows).
3. The output is located in ./dist/html5-qrcode.min.js.

When using a module loader (e.g., npm, Yarn, Webpack, Vite), import the specific classes you need from the html5-qrcode package. Use Html5QrcodeScanner for a high-level scanner UI or Html5Qrcode for low-level camera control.

// To use Html5QrcodeScanner
import {Html5QrcodeScanner} from "html5-qrcode"

// To use Html5Qrcode
import {Html5Qrcode} from "html5-qrcode"

The library provides two distinct API levels depending on your integration needs:

• Html5QrcodeScanner (Easy Mode): An end-to-end scanner that includes a built-in user interface. It can be integrated with minimal code (less than ten lines).
• Html5Qrcode (Pro Mode): A low-level API that provides a powerful set of tools to build your own custom user interface. This mode allows you to handle camera setup, permissions, and code reading without the library managing the UI components.

The library supports using the native browser BarcodeDetector API, which can provide significantly better scanning performance compared to the standard ZXing library.

Note: This feature has graduated from the experimental configuration and is now part of Html5QrcodeConfigs. It is enabled by default.

Performance improvements are most notable on mobile devices and low-end Android hardware, where scanning latency can be reduced by up to 75-80%.

The start() method accepts a configuration object to control scanning behavior and UI. Most fields have default values. If you want to use defaults, pass an empty object {}.

// Example of a configuration object
let config = {
  fps: 10,
  qrbox: { width: 100, height: 100 },
  rememberLastUsedCamera: true
};

By default, the library scans all supported formats. You can restrict scanning to a specific subset of formats to improve performance or limit functionality. Supported formats include QR_CODE, AZTEC, CODE_128, EAN_13, UPC_A, etc.

// Scanning only QR codes with Html5Qrcode
const html5QrCode = new Html5Qrcode(
  "reader", 
  { formatsToSupport: [ Html5QrcodeSupportedFormats.QR_CODE ] }
);

// Scanning specific formats with Html5QrcodeScanner
const formatsToSupport = [
  Html5QrcodeSupportedFormats.QR_CODE,
  Html5QrcodeSupportedFormats.UPC_A
];

const html5QrcodeScanner = new Html5QrcodeScanner(
  "reader",
  {
    fps: 10,
    formatsToSupport: formatsToSupport
  },
  false
);
html5QrcodeScanner.render(onScanSuccess);

The TorchButtonOptions interface defines the initial CSS styling for the torch button during creation.

export interface TorchButtonOptions {
    display: string;
    marginLeft: string;
}

Use Html5QrcodeCameraScanConfig to tune the behavior of the camera-based scanner during the start() method.

Keys:

• fps (number): The expected framerate of scanning (e.g., { fps: 2 } scans every 500ms).
• qrbox (number | QrDimensions | QrDimensionFunction): Defines the scanning region. Can be a fixed size, a QrDimensions object, or a function that calculates size based on video stream dimensions. If not set, the entire video area is scanned.
• aspectRatio (number): The desired aspect ratio for the video feed (e.g., 1.777 for 16:9).
• disableFlip (boolean): If true, flipped (mirrored) QR codes will not be scanned.
• videoConstraints (MediaTrackConstraints): Overrides other parameters like aspectRatio or facingMode using standard Web API constraints.

The qrbox configuration option defines the scanning region (the 'shaded' area) in the viewfinder. It can be provided in three formats:

1. A number: Sets both width and height to the same value.
2. A QrDimensions object: An object specifying exact { width, height } in pixels.
3. A function: A callback that receives the current viewfinderWidth and viewfinderHeight and returns a QrDimensions object.

Important Constraints:

• The qrbox dimensions must not be larger than the root element (the container) of the scanner. If the width is larger, it will be truncated to the width of the root element.
• If the qrbox height is greater than the height of the video stream, the shading effect will be ignored.
• If using an object, both width and height must be explicitly set.