A Barcode Detection API ponyfill/polyfill that uses ZXing-C++ WebAssembly under the hood.

Supported barcode formats:

To install, run the following command:

npm i barcode-detector

import { BarcodeDetector } from "barcode-detector/ponyfill";

To avoid potential namespace collisions, you can also rename the export:

import { BarcodeDetector as BarcodeDetectorPonyfill } from "barcode-detector/ponyfill";

A ponyfill is a module required to be explicitly imported without introducing side effects. Use this subpath if you want to avoid polluting the global object with the BarcodeDetector class, or if you intend to use the implementation provided by this package instead of the native one.

import "barcode-detector/polyfill";

This subpath is used to polyfill the native BarcodeDetector class. It will automatically register the BarcodeDetector class in the global object if it's not already present.

import { BarcodeDetector } from "barcode-detector/ponyfill";
globalThis.BarcodeDetector ??= BarcodeDetector;

import { BarcodeDetector } from "barcode-detector";

This approach combines the ponyfill and polyfill approaches.

For modern browsers that support ES modules, this package can be imported via the <script type="module"> tags:

1. Include the polyfill:

   <!-- register -->
   <script
     type="module"
     src="https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/es/polyfill.min.js"
   ></script>
   
   <!-- use -->
   <script type="module">
     const barcodeDetector = new BarcodeDetector();
   </script>

2. Script scoped access:

   <script type="module">
     import { BarcodeDetector } from "https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/es/ponyfill.min.js";
     const barcodeDetector = new BarcodeDetector();
   </script>

3. With import maps:

   <!-- import map -->
   <script type="importmap">
     {
       "imports": {
         "barcode-detector/ponyfill": "https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/es/ponyfill.min.js"
       }
     }
   </script>
   
   <!-- script scoped access -->
   <script type="module">
     import { BarcodeDetector } from "barcode-detector/ponyfill";
     const barcodeDetector = new BarcodeDetector();
   </script>

For legacy browsers or userscripts that lack support for <script type="module"> tags, IIFE is the preferred choice. Upon executing the IIFE script, a variable named BarcodeDetectionAPI will be registered in the global window by var declaration.

<!-- 
  IIFE ponyfill.js registers:
  window.BarcodeDetectionAPI.BarcodeDetector
  window.BarcodeDetectionAPI.prepareZXingModule
  -->
<script src="https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/iife/ponyfill.min.js"></script>

<!-- 
  IIFE polyfill.js registers:
  window.BarcodeDetector
  window.BarcodeDetectionAPI.prepareZXingModule
  -->
<script src="https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/iife/polyfill.min.js"></script>

<!-- 
  IIFE index.js registers:
  window.BarcodeDetector
  window.BarcodeDetectionAPI.BarcodeDetector
  window.BarcodeDetectionAPI.prepareZXingModule
  -->
<script src="https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/iife/index.min.js"></script>

The core barcode reading functionality of this package is powered by zxing-wasm. Therefore, a .wasm binary file is fetched at runtime. By default, the .wasm serving path is initialized with a jsDelivr CDN URL. However, there're cases where this is not desired, such as the allowed serving path is white-listed by the Content Security Policy (CSP), or offline usage is required.

To customize the .wasm serving path, this package reexports prepareZXingModule along with ZXING_WASM_VERSION, ZXING_WASM_SHA256 and ZXING_CPP_COMMIT from zxing-wasm. For more details on how to use them, please check Configuring .wasm Serving and Controlling .wasm Instantiation Timing and Caching sections in the zxing-wasm repository.

An example usage to override the .wasm serving path with an unpkg.com CDN url is as follows:

import {
  BarcodeDetector,
  ZXING_WASM_VERSION,
  prepareZXingModule,
} from "barcode-detector/ponyfill";

// Override the locateFile function
prepareZXingModule({
  overrides: {
    locateFile: (path, prefix) => {
      if (path.endsWith(".wasm")) {
        return `https://unpkg.com/zxing-wasm@${ZXING_WASM_VERSION}/dist/reader/${path}`;
      }
      return prefix + path;
    },
  },
});

// Now you can create a BarcodeDetector instance
const barcodeDetector = new BarcodeDetector({
  formats: ["qr_code"],
});

Please check the spec, MDN doc and Chromium implementation for more information.

An example usage is as follows:

import { BarcodeDetector } from "barcode-detector/ponyfill";

// check supported formats
const supportedFormats = await BarcodeDetector.getSupportedFormats();

const barcodeDetector: BarcodeDetector = new BarcodeDetector({
  // make sure the formats are supported
  formats: ["qr_code"],
});

const imageFile = await fetch(
  "https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=Hello%20world!",
).then((resp) => resp.blob());

barcodeDetector.detect(imageFile).then(console.log);

The source code in this repository is licensed under the MIT license.