Getting Started with Quagga2

This guide will help you install Quagga2 and get your first barcode scanner running quickly.

What is Quagga2?

Quagga2 is a JavaScript barcode scanner library that works in both browsers and Node.js. It can:

Unlike some libraries, Quagga2 includes a barcode locator that can find and decode barcodes regardless of their rotation or scale in the image.

Installation

Using NPM (Recommended)

npm install --save @ericblade/quagga2

Then import it in your project:

// ES6 modules
import Quagga from '@ericblade/quagga2';

// CommonJS (important: note the .default)
const Quagga = require('@ericblade/quagga2').default;

Using CDN (Script Tag)

Add one of these script tags to your HTML:

Unminified version (useful for development):

<script src="https://cdn.jsdelivr.net/npm/@ericblade/quagga2/dist/quagga.js"></script>

Minified version (recommended for production):

<script src="https://cdn.jsdelivr.net/npm/@ericblade/quagga2/dist/quagga.min.js"></script>

Specific version (recommended to avoid breaking changes):

<script src="https://cdn.jsdelivr.net/npm/@ericblade/quagga2@1.8.4/dist/quagga.min.js"></script>

The script tag exposes the library globally as Quagga.

Basic Usage - Live Camera Scanning

Here’s a minimal example to scan barcodes using your device’s camera:

HTML

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Quagga2 Barcode Scanner</title>
</head>
<body>
  <div id="scanner-container"></div>
  <script src="https://cdn.jsdelivr.net/npm/@ericblade/quagga2/dist/quagga.min.js"></script>
  <script src="app.js"></script>
</body>
</html>

JavaScript (app.js)

Quagga.init({
  inputStream: {
    type: "LiveStream",
    target: document.querySelector('#scanner-container')
  },
  decoder: {
    readers: ["code_128_reader"]
  }
}, function(err) {
  if (err) {
    console.error(err);
    return;
  }
  console.log("Initialization finished. Ready to start");
  Quagga.start();
});

Quagga.onDetected(function(result) {
  const code = result.codeResult.code;
  console.log("Barcode detected:", code);
  alert("Found barcode: " + code);
});

That’s it! This will:

  1. Request camera access
  2. Display the camera feed in #scanner-container
  3. Continuously scan for CODE 128 barcodes
  4. Alert you when a barcode is detected

Basic Usage - Static Image Scanning

To decode a barcode from an existing image:

Quagga.decodeSingle({
  src: "path/to/your/image.jpg",
  decoder: {
    readers: ["code_128_reader"]
  }
  // Note: Images are scaled to 800px (longest side) by default.
  // See inputStream.size in the Configuration Reference for details.
}, function(result) {
  if (result && result.codeResult) {
    console.log("Barcode found:", result.codeResult.code);
  } else {
    console.log("No barcode found");
  }
});

Important Notes

HTTPS Required

For security reasons, browsers require HTTPS to access the camera, except on localhost. If you host your app on a domain, you must use https://.

Browser Compatibility

Quagga2 works in modern browsers that support:

See the Browser Support page for detailed compatibility information.

Polyfill Recommendation

Different browsers implement camera APIs differently. We recommend including webrtc-adapter for better compatibility:

<script src="https://webrtc.github.io/adapter/adapter-latest.js"></script>

Next Steps

Now that you have the basics working:

Common Issues

Camera Permission Denied

If the user denies camera access, the init callback will receive an error. Always handle this gracefully:

Quagga.init(config, function(err) {
  if (err) {
    if (err.name === 'NotAllowedError') {
      alert('Please allow camera access to scan barcodes');
    }
    console.error(err);
    return;
  }
  Quagga.start();
});

Camera Not Found

Some devices don’t have a camera (desktops, VMs). Check for camera availability:

if (navigator.mediaDevices && typeof navigator.mediaDevices.getUserMedia === 'function') {
  // Camera API available
  Quagga.init(config, callback);
} else {
  // Fallback to file upload
  alert('Camera not available, please upload an image');
}

No Barcode Detected

If Quagga2 isn’t detecting your barcode:

Getting Help