web-native-qr-scanner

A React QR / barcode scanner component for the browser. It prefers the browser's native BarcodeDetector API (Safari 17.4+, Chrome/Edge) for near-native scanning speed, and transparently falls back to zxing-wasm (ZXing-C++ compiled to WebAssembly) on devices/browsers without native support.

Features

• Native-first, WASM fallback — tries BarcodeDetector first, falls back to zxing-wasm if unsupported or after 5s of native misses.
• ROI cropping — only decodes the pixels inside the visible scan frame (matching what object-cover actually displays), instead of the full camera frame. Faster decoding and fewer false positives from codes outside the frame — the same approach apps like Zalo use.
• requestVideoFrameCallback — schedules decode attempts on the video's actual render cadence instead of blindly polling on a timer.
• QR and 1D barcode modes — code_128, code_39, ean_13, ean_8, upc_a, upc_e, itf, codabar.
• Torch/flashlight toggle, multi-code picker sheet, permission-denied state, i18n-able labels.
• Zero UI dependencies — icons are inlined, styling ships as a plain CSS file (works with or without Tailwind).

Install

npm install web-native-qr-scanner

react and react-dom (>=18) are peer dependencies.

Usage

import { QrScanner } from 'web-native-qr-scanner'
import 'web-native-qr-scanner/style.css'

function ScanPage() {
  return (
    <QrScanner
      mode="qr" // or "barcode"
      onDetect={(code) => console.log('scanned:', code)}
    />
  )
}

Props

| Prop | Type | Default | Description | | ----------- | ------------------------- | ------------ | ------------------------------------------------ | | onDetect | (code: string) => void | — | Called once with the decoded text. | | mode | 'qr' \| 'barcode' | 'barcode' | Restricts which formats are detected. | | className | string | — | Extra class name on the root element. | | labels | QrScannerLabels | English | Override any UI string for i18n. |

Custom labels

<QrScanner
  mode="barcode"
  onDetect={handleCode}
  labels={{
    hintBarcode: 'Đưa barcode vào khung hình',
    permissionDeniedTitle: 'Không thể truy cập camera',
  }}
/>

Browser support

Camera access requires a secure context (HTTPS, or localhost). Native detection requires BarcodeDetector (Safari 17.4+, Chrome/Edge 83+); everything else uses the WASM fallback automatically, so the component works on any browser that supports getUserMedia.

Development

npm install
npm run build      # bundle to dist/ (ESM + CJS + .d.ts + style.css)
npm run typecheck

Publishing

npm login
npm publish

License

MIT